Version 46 (modified by Gedare, on Feb 29, 2012 at 9:19:34 PM) (diff)

/* GIT Access for users */

RTEMS GIT Repository

RTEMS project's revision control tool is GIT and the git repositories can be located at

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

  • 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 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. Only a small subset of selected people have write permission, but everyone is welcome to commit a patch with proper licensing. See the Git Users? page with instructions and some useful git commands.

Browse the GIT Repository Online

You can browse our GIT history of all available repositories online by accessing

Using the GIT Repository

The following examples demostrate how to use the RTEMS' git repo. These examples are provided for the main rtems module, but they are also valid for the other modules.

First we need to obtain our own local copy of the RTEMS git repository:

 git clone git:// rtems

This command will create a folder named rtems in the current directory. This folder will contain a full featured rtems' git repository and the current HEAD revision checked out. Since all the history is available we can checkout any release of RTEMS. Major RTEMS releases are available as separate branches in the repo.

To see all available remote branches issue the following command:

 git branch -r

We can checkout one of those remote branches (e.g. rtems-4.10 branch) using the command:

 git checkout -b rtems410 origin/4.10

This will create a local branch named "rtems410", containing the rtems-4.10 release, that will track the remote branch "rtems-4-10-branch" in origin (git:// The 'git branch' command prints a list of the current local branches, indicating the one currently checked out.

If you want to switch between local branches:

 git checkout <branch-name>

With time your local repository will diverge from the main RTEMS repository. To keep your local copy up to date you need to issue:

 git pull origin

This command will update all your local branches with any new code revisions available on the central repository.

Making Changes

Git allows you to make changes in the RTEMS source tree and track those changes locally. First you need to clone the repository:

 git clone git:// rtems

Or if you already cloned it before, then you might want to update to the latest version before making your changes:

 cd rtems
 git pull

Next make your changes to files. If you add, delete or move/rename files you need to inform Git

 git add /some/new/file
 git rm /some/old/file
 git mv /some/old/file /some/new/file

When you're satisfied with the changes you made, commit them (locally)

 git commit -a

The -a flag commits all the changes that were made, but you can also control which changes to commit by individually adding files as you modify them by using. You can also specify other options to commit, such as a message with the -m flag.

 git add /some/changed/files
 git commit

But you shouldn't do any of this on the branch that you cloned, instead you should create a new branch to work with, so that the cloned branch (master) is a pristine copy of the upstream RTEMS repository.

Working with Branches

Branches facilitate trying out new code and creating patches.

Previous release of RTEMS are available through remote branches. To check out a remote branch, first query the Git repository for the list of branches:

 git branch -r

Then checkout the desired remote branch, for example:

 git checkout -b rtems410 origin/4.10

Or if you have previously checked out the remote branch then you should see it in your local branches:

 git branch

You can change to an existing local branch easily:

 git checkout rtems410

You can also create a new branch and switch to it:

 git branch temporary
 git checkout temporary

Or more concisely:

 git checkout -b temporary

If you forget which branch you are on

 git branch

shows you by placing a * next to the current one.

When a branch is no longer useful you can delete it.

 git checkout master
 git branch -d temporary

If you have unmerged changes in the old branch git complains and you need to use -D instead of -d.

Viewing Changes

To view all changes since the last commit:

 git diff HEAD

To view all changes between the current branch and another branch, say master:

 git diff master..HEAD

To view descriptions of committed changes:

 git log

Or view the changeset for some file (or directory):

 git log /some/file

To view the changesets made between two branches:

 git log master..HEAD

Or for a more brief description use shortlog:

 git shortlog master..HEAD

Reverting Changes

To remove all (uncommitted) changes on a branch

 git checkout -f

Or to selectively revert (uncommited) files, for example if you accidentally deleted ./some/file

 git checkout -- ./some/file


 git checkout HEAD ./some/file

To remove commits there are two useful options, reset and revert. git reset should only be used on local branches that no one else is accessing remotely. git revert is cleaner, and is the right way to revert changes that have already been pushed/pulled remotely.

git reset

git reset is a powerful and tricky command that should only be used on local (un-pushed) branches): A good description of what it enables to do can be found here. The following are a few useful examples. Note that adding a ~ after HEAD refers to the most recent commit, and you can add a number after the ~ to refer to commits even further back; HEAD by itself refers to the current working directory (changes since last commit).

git reset HEAD~

Will undo the last commit and unstage those changes. Your working directory will remain the same, therefore a "git status" will yield any changes you made plus the changes made in your last commit. This can be used to fix the last commit. You will need to add the files again.

git reset --soft HEAD~

Will just undo the last commit. The changes from last commit will still be staged (just as if you finished git adding them). This can be used to amend the last commit (e.g. I forgot to add a file to the last commit).

git reset --hard HEAD~

Will revert everything, including the working directory, to the previous commit. This is dangerous and can lead to you losing all your changes; the --hard flag ignores errors.

git reset HEAD

Will unstage any change. This is used to revert a wrong git add. (e.g. I added a file that shouldn't be there, but I haven't 'committed')

git reset --hard HEAD

Will revert your working directory to a HEAD state. You will lose any change you made to files after the last commit. This is used when you just want to destroy all changes you made since the last commit.

git revert

git revert does the same as reset but creates a new commit with the reverted changes instead of modifying the local repository directly.

 git revert HEAD

This will create a new commit which undoes the change in HEAD. You will be given a chance to edit the commit message for the new commit.

Merging Changes

Suppose you commit changes in two different branches, branch1 and branch2, and want to create a new branch containing both sets of changes:

 git checkout -b merged
 git merge branch1
 git merge branch2

Or you might want to bring the changes in one branch into the other:

 git checkout branch1
 git merge branch2

And now that branch2 is merged you might get rid of it:

 git branch -d branch2

If you have done work on a branch, say branch1, and have gone out-of-sync with the remote repository, you can pull the changes from the remote repo and then merge them into your branch:

 git checkout master
 git pull
 git checkout branch1
 git merge master

If all goes well the new commits you pulled into your master branch will be merged into your branch1, which will now be up-to-date. However, if branch1 has not been pushed remotely then rebasing might be a good alternative to merging because the merge generates a commit


An alternative to the merge command is rebase, which replays the changes (commits) on one branch onto another. git rebase finds the common ancestor of the two branches, stores each commit of the branch you’re on to temporary files, and applies each commit in order.

For example

 git checkout branch1
 git rebase master

or more concisely

 git rebase master branch1

will bring the changes of master into branch1, and then you can fast-forward master to include branch1 quite easily

 git checkout master
 git merge branch1

Rebasing makes a cleaner history than merging; the log of a rebased branch looks like a linear history as if the work was done serially rather than in parallel. A primary reason to rebase is to ensure commits apply cleanly on a remote branch, e.g. when submitting patches to RTEMS that you create by working on a branch in a personal repository. Using rebase to merge your work with the remote branch eliminates most integration work for the committer/maintainer.

There is one caveat to using rebase: Do not rebase commits that you have pushed to a public repository. Rebase abandons existing commits and creates new ones that are similar but different. If you push commits that others pull down, and then you rewrite those commits with git rebase and push them up again, the others will have to re-merge their work and trying to integrate their work into yours can become messy.

Creating a Patch

The easiest way to create a patch is to make and commit changes in a branch and then use either diff or format-patch comparing against the upstream master branch. (Of course, if the patch is supposed to be against a different branch then you should substitute that branch's name for master.)

 git diff master..HEAD > ../rtems.diff

Creates a diff containing the changes made in the current branch's commits since the master branch. Here I redirected the output to a file in the parent directory.

 git format-patch master

Creates a separate patch for each commit that has been made between the master branch and the current branch's head. These files, appended with .patch, are formatted so they can be emailed and rely on having git configured with your name and email address, for example

 git config --global "Your Name"
 git config --global

Submit your patch to the rtems-devel mailing list? and if the patch fixes a bug, file a PR on the Bugzilla?.

GIT Access for contributors

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, If you have been granted commit access and do have an account on 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
[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://
# cd rtems

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

# git remote add upstream ssh://
# git fetch upstream

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

Check your setup

git remote show origin

Should print something similar to

 * remote origin
   Fetch URL: ssh://
   Push  URL: ssh://
   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
 *  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


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


Some restrictive corporate firewalls block access through the git protocol (git://) If you are unable to reach the server git:// you can try accessing through http. To clone the rtems repository using the http protocol use the following command:

git clone rtems

This access through http is slower (way slower!) than through the git protocol therefore the git protocol is preferred.

Learn more about Git

Links to site with good Git information.

Attachments (1)

Download all attachments as: .zip