wiki:Developer/Git

Version 47 (modified by Gedare, on Feb 29, 2012 at 9:27:21 PM) (diff)

/* Move content */ Move the sub-heading under GIT Access for users to a new page.

RTEMS GIT Repository

RTEMS project's revision control tool is Git and the git repositories can be located at http://git.rtems.org/.

Why git?

Git is a distributed revision control system with an emphasis on speed and data safety. With git revision control system each user has a full featured copy of the main repository. Each revision control operation is done in the local repository and can be later shared using patches or by direct push to the main repository.

RTEMS Git Repositories

The following modules are in the RTEMS GIT Repository and currently actively used for development. The complete list of available development modules can be found at http://git.rtems.org/

  • rtems.git - RTEMS Itself
  • Examples
    • examples-v2.git - RTEMS Examples (merges all other non-networked example collections)
    • network-demos.git - Example RTEMS Networking Programs
  • rtems-testing.git - Helpful scripts for testing. Includes Simulator Scripts, Coverage Testing help, git helpers, RTEMS testing, and GCC testing aids.
  • rtems-addon-packages.git - Free software libraries that have been ported to RTEMS including AVL, TCL, ncurses, readline, and zlib.
  • rtems-graphics-toolkit.git - Graphic support libraries for RTEMS.
  • rtems-schedsim-git - Scheduling Simulator

RTEMS Git Server

RTEMS has a dedicated Git server. The machine runs cgit to provide a web interface to GIT, the GIT protocol for direct read-only access and ssh accounts for those with commit access. The configuration is standard with the only hook currently used to send commit details to the rtems-vc@… mailing list.

Git Access for Users

The git repository is available read-only to the public at large, and anyone is welcome to submit a patch (with proper licensing) by mailing it to the Mailing Lists? or Bugzilla?. See the Git Users? page for access instructions and some useful git commands.

Git Access for Committers

A small set of selected people have write permission. TODO: Some guidelines for anyone who wishes to contribute to rtems... Patches? Pull Requests?...

The preferred workflow for making changes to RTEMS is to push patches to a committer's personal repository in public view and then merge changes from there. For working on enhancements or bug fixes committers are encouraged to push to branches on their personal repositories and to merge into the main RTEMS repository from their personal repository. Personal branches should not be pushed to the RTEMS repository.

SSH Access

Currently all committer's should have an ssh account on the main git server, git.rtems.org. If you have been granted commit access and do have an account on git.rtems.org one should be requested on the rtems-devel@… list. SSH access for git uses key logins instead of passwords. The key should be at least 1024bits in length.

Personal Repository

Personal repositories keeps the clutter away from the master repository. A user with a personal repository can make commits, create and delete branches, plus more without interfering with the master repository. Commits to the master repository generate email to the rtems-vc@… list and development type commits by a developer would only add noise and lessen the effectiveness of the commit list.

A committer should maintain a personal clone of the RTEMS repository through which all changes merged into the RTEMS head are sent. The personal repository is also a good place for committers to push branches that contain works in progress. The following instructions show how to setup a personal repository that by default causes commits to go to your private local repository and pushes to go to your publicly visible personal repository. The RTEMS head is configured as a remote repository named 'upstream' to which you can push changes that have been approved for merging into RTEMS.

Branches aren't automatically pushed until you tell git to do the initial push after which the branch is pushed automatically. In order to keep code private just put it on a branch in your local clone and do not push the branch.

Create a personal repository

Set up the server side repository. In the following substitute user with your username.

# ssh git.rtems.org
[user@git ~]$ ln -s /data/git/user git
[user@git ~]$ ls -l
lrwxrwxrwx 1 user rtems 16 Feb  1 11:52 git -> /data/git/user
[user@git ~]$ cd git
[user@git git]$ git clone --mirror /data/git/rtems.git

Provide a description for the repository, for example "Clone of master repository."

[user@git git]$ echo "Clone of master repository." > rtems.git/description
[user@git git]$ logout

Clone the repository on your local machine

# git clone ssh://user@git.rtems.org/home/user/git/rtems.git
# cd rtems

Add the RTEMS repository as a remote repository and get the remote tags and branches

# git remote add upstream ssh://user@git.rtems.org/data/git/rtems.git
# git fetch upstream

After a little while you should be able to see your personal repo at http://git.rtems.org/user/rtems.git/ and you can create other repositories in your git directory that will propagate to http://git.rtems.org/user if you need.

Check your setup

git remote show origin

Should print something similar to

 * remote origin
   Fetch URL: ssh://user@git.rtems.org/home/user/git/rtems.git
   Push  URL: ssh://user@git.rtems.org/home/user/git/rtems.git
   HEAD branch: master
   Remote branches:
     4.10   tracked
     4.8    tracked
     4.9    tracked
     master tracked
   Local branch configured for 'git pull':
     master merges with remote master
   Local ref configured for 'git push':
     master pushes to master (up to date)

Push commits to personal repo master from local master

# git push

Push a branch onto personal repo

# git push origin branchname

Update from upstream master (RTEMS head)

When you have no changes in your local master branch, use

 # git fetch upstream
 # git checkout master
 # git merge upstream/master

This is the same as a git pull.

Update and commit to RTEMS

When you have changes and you want to propagate them upstream: (if you have those changes on a separate branch)

# git checkout new_features
# git fetch upstream
# git rebase upstream/master
# git push upstream new_features:master

If someone pushed since you updated the server rejects your push until you are up to date.

GIT Push Configuration

People with write access to the main repository should make sure that they push the right branch with the git push command. The above setup ensures that git push will not touch the main repository, which is identified as upstream, unless you specify the upstream (by git push upstream master).

Lets suppose we have a test branch intended for integration into the master branch of the main repository.

# git branch
  master
 *  test

There are two options for pushing with the branch. First,

# git push origin test

Will push the test branch to the personal repository. To delete the remote branch

# git push origin :test

You'll still need to delete your local branch if you are done with it.

If you are going to work exclusively with one branch for awhile, you might want to configure git to automatically push that branch when you use git push. By default git push will use the local master branch, but you can use the 'test' branch as the source of your changes:

# git config remote.origin.push test:master

Now git push will merge into your master branch on your personal repository. You can also setup a remote branch:

# git config remote.origin.push test:test

You can see what branch is configured for pushing with

# git remote show origin

And reset to the default

# git config remote.origin.push master

Committing

When merging someone's work, whether your own or otherwise, we have some suggested procedures to follow.

  • Never work in the master branch. Checkout a new branch and apply patches/commits to it.
  • Before pushing upstream:
    • Update master by fetching from the server
    • Rebase the working branch against the updated master
    • Push the working branch to the server master

The basic workflow looks like

# git checkout -b somebranch upstream/master
# patch .. git add/rm/etc
# git fetch upstream
# git rebase upstream/master
# git push upstream somebranch:master

Learn more about Git

Links to site with good Git information.

Attachments (1)

Download all attachments as: .zip