This page presents how to work with the LinShim6 git repository, but is also intended at sharing my experience about git usage. Don't hesitate to comment about it (mail to Sébastien Barré) or suggests practical tricks allowing to better benefit from the power of git.

Initial configuration of git


git-config --global user.name "FirstName LastName"
git-config --global user.email "user@example.com"

(retrieved from http://www.sourcemage.org/Git_Guide)
(edit by Damien Leroy : for MacOS, see http://tumble.toolmantim.com/post/30619331/standard-git-config-on-osx)

Creating the initial local copy of the repository


git-clone git://scm.info.ucl.ac.be/LinShim6.git

This creates the initial copy, and checks out the master branch.
If you want to see what are the other branches, type:

git-remote show origin

'origin' is the name related to the original remote repository (you can register other remote repositories with the 'git-remote' add). Each registered remote repository is stored in the file .git/config.

Making remote branches local

For the userspace part (kernel-space is described later in this page), the master branch always contains the current most stable version of LinShim6. It may be even more stable than the last release, since it contains always the latest bug fixes for the last release.

At the moment of writing this page, the latest stable release is 0.8.2, but some bug fixes have already been committed. After some time or sufficiently important bugs have been fixed, we release a new intermediate version. In the current case, it will be 0.8.3. At any moment, the state of the implementation tree can be observed with gitk:

gitk

It shows a graphical view of the commit history. For example you can observe that the 0.8.2 version is tagged,and that some newer commits appear above. With each commit comes a comment that describes its content. The commit that just follows the 0.8.2 tag is not so precise because it contains the aggregated modifications made with svn, before we went to git.

In the same time as we add bug fixes to 0.8.2, we develop new features for LinShim6. This needs much more testing and can result sometimes in completely unstable or non-working states. We thus create a new branch called 0.9, that allows us working on new features/major revisions without impacting the stable release.
If you want to be able to work on that branch, you must track it:

git-checkout --track -b 0.9 origin/0.9

That commands does several things:

• create a local branch called 0.9
• set it to track the remote branch of the same name (located in the remote repository referenced under the name 'origin', see above)
• sets the new local 0.9 branch current

If then you type

git-branch

You will see that your local copy of the repository has now two branches, and the 0.9 branch is marked with a star, indicating that 0.9 is the current branch.

While the 0.9 branch holds the general architectural revisions, other branches based on that 0.9 hold specific current tasks under work. For each task you are interested in, you can get a copy of the related branch in your local repository. For example if you are interested in all current branch (at the time of writing this page):

git-checkout --track -b multipath origin/multipath
git-checkout --track -b tcp_hint origin/tcp_hint


Getting the kernel sources:git subproject

The kernel part of LinShim6 is managed as a git subproject. That is, there is a separate repository for the kernel, which is made accessible from inside the userspace git project through the subproject mechanism. We do that in order to be able to synchronize with the mainline Linux repository.

You may have noticed that the LinShim6-kernel directory is empty. In fact you have the option of only working on the userspace part if you want. To get the content of the directory, type (in the parent directory of LinShim6-kernel):

git-submodule init
git-submodule update


The kernel code management differs from that of the userspace in that the master branch tracks the official Linux repository. There is nothing related to Shim6 in that branch. Thus there is a branch called LinShim6 that olds the latest stable version. Note that you have now a .git directory in both LinShim6 and LinShim6-kernel, because you are actually dealing with two repositories. Thus when you are under LinShim6-kernel, you can note that the names for the branches are different.
Except for the stable branch which is called LinShim6, all other branches are prefixed with 'kernel-' to distinguish them from the userspace branches.

Again, to get all branches related to the kernel (in the LinShim6-kernel directory):

git-checkout --track -b LinShim6 origin/LinShim6
git-checkout --track -b kernel-0.9 origin/kernel-0.9
git-checkout --track -b kernel-module origin/kernel-module
git-checkout --track -b kernel-multipath origin/kernel-multipath
git-checkout --track -b kernel-tcp_hint origin/kernel-tcp_hint

Of course this list is subject to change, type

git-branch -r

to see the current list of remote branches. (that is branches stored in the LinShim6 repository).

Commiting work and sending it to a repository/mail/...

Getting information about the repository


git-status

Will list you the set of files that have been modified since the last commit, as well as the set of untracked files.


gitk


Gives you a graphical view of the history for the current branch

TODO : explain HEAD^

Undoing things

Undo local work

To undo any local since the last commit:

git-reset --hard

Note that this will revert any local change. not the subproject. Thus if you type that in the userspace part of LinShim6, git-status may still tell you afterwards that the LinShim6-kernel folder has been modified. You can safely ignore that.

Split commits

(retrieved from http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html)


git-rebase --interactive <commit>^

Mark the commit you want to split with the action 'edit'. When it comes to editing this commit:

git-reset HEAD^