wiki:Developer/Git

Version 23 (modified by Sh, on Jan 27, 2012 at 1:03:04 PM) (diff)

/* GIT Access for contributors */

RTEMS GIT Repository

RTEMS project is currently in the process of migrating its CVS repositories to GIT. A git repository has already been setup and is currently available for testing at http://git.rtems.org/. The conversion plan for this undergoing migration can be consulted in the CVS to GIT wiki page.

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, CVS helpers, RTEMS atesting, 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

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.

Browse the GIT Repository Online

You can browse our GIT history of all available repositories online by accessing http://git.rtems.org/.

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://git.rtems.org/rtems.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://git.rtems.org/rtems.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://git.rtems.org/rtems.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

 git checkout -- /some/file
 git checkout HEAD /some/file

To remove commits there are two useful options, reset and revert; revert is cleaner, and is the right way to revert changes that have already been pushed/pulled remotely.

 git reset HEAD-1

Removes the last 1 (or any other number you put) commit from the current branch. git reset should only be used on local branches that no one else is accessing remotely. This is a very powerful and tricky command; A good description of what it enables to do can be found here

 git revert HEAD~1

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

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

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 user.name "Your Name"
 git config --global user.email name@domain.com

See the Bugzilla? page for information about submitting patches to RTEMS.

GIT Access for contributors

TODO: Some guidelines for anyone who wishes to contribute to rtems... Patches? Pull Requests?...

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. Lets suppose we have an upstream branch intended for integration into the master branch of the main repository, then we can check the configuration with the following command

git remote show origin

which may print out

  • remote origin Fetch URL: user@…:git/rtems.git Push URL: 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':

upstream merges with remote master

Local ref configured for 'git push':

upstream pushes to master (up to date)

Here you can see that you pull from the remote master branch into your local upstream branch and push in the other direction. After the clone of the repository the master branch will be used as the default push branch. You can change this with

git config remote.origin.push upstream:master

Troubleshooting

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

git clone http://git.rtems.org/rtems/ 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