View source for Linux sources

== Introduction ==

Getting Linux sources for boards used at our department requires these steps:
# Getting [http://kernel.org vanilla Linux sources]
# Applying several patches to these sources

The reason for providing the patches separately is that for many users it is important to know which patches were applied to the kernel they are using. The maintenance of the additional patches is not an easy task as these patches evolve in time. They are either being ported to newer Linux versions or being updated for other readons.

To maintain the patches we have decided to use the tool [http://repo.or.cz/w/topgit.git TopGit]. This page describes how this tool is used for our Linux sources.


== TopGit overview ==

[http://repo.or.cz/w/topgit.git TopGit] is a tool manage patches as so called topic branches in Git repositories. Every patch is represented by one branch. The history of patch evolution is tracked on that branch. As some patches might depend on other patches, TopGit also manages these dependencies.

For more information check the [http://repo.or.cz/w/topgit.git?a=blob;f=README TopGit README].

== Linux repositories ==

We maintain the following Linux repositories:
* [http://rtime.felk.cvut.cz/gitweb/shark/linux.git Shark 5200]

=== Layout ===

Our Linux repositories have the following branches:

;vanilla : Tracks vanilla linux sources.
;patch/* : Topic branches for individual patches. These branches are managed using TopGit.
;<board>/<version> : Branch with TopGit patches exported as plain git commits.
;HEAD : Symbolic reference to ''<board>/<version>'' branch we consider as stable.

== Managing TopGit patches ==

=== Cloning a TopGit managed repository ===

 git clone <some-url/linux.git>
 cd linux
 git branch vanilla origin/vanilla
 tg remote --populate origin

=== Updating patches ===

 git checkout vanilla
 git pull git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git tag v2.6.29-rc1
 tg summary  # patches marked by 'D' must be updated
 git checkout patch/...
 tg update
 ...

=== Exporting patches ===

To make accessing kernel sources easier for users who just want the sources for the board they use, we provide branches witch all the needed patches exported from TopGit.

 git checkout patch/<last patch>
 tg export shark/<version>

This creates branch shark/''<version>'' with current vanilla sources and all patches that depend on patch/''<last patch>'' applied on it.

=== Porting patches to -stable linux version ===

Most patches are based against ''vanilla'' branch. Therefore <tt>tg update</tt> updates the patches against newer vanilla sources. Stable kernels (2.6.x.y) are maintained as separate branches and for that reason TopGit wont do the update for us.

I use the following commands to prepare a version based on 2.6.26.5 assuming that vanilla is at 2.6.26
 tg export tmp
 git rebase v2.6.26.5 tmp
 git branch -m tmp shark/2.6.26.5

=== Updating branch with exported patches ===

When you change some patch, you may want to update the branch with exporte patches (e.g. shark/2.6.28.8). The simplest solution is to delete that branch and reexport it again. The drawback of this solution is that uses of the exported branch cannot pull your changes without manually merging it. It is therefore preferred to do the merge locally and push the result of merge.

 # Prepare the new branch as in the previous section
 tg export updated-patches
 git rebase v2.6.28.8 updated-patches
 # Merge the result to the existing branch
 git checkout shark/2.6.28.8
 git merge updated-patches
 git branch -d updated-patches   # delete the temporary branch

=== Developing a new patch ===

''Based on martin f. krafft's HOWTO-tg2quilt''.

If you want to develop a new feature (or bug fix), first choose the
base for it. It will be wither  ''vanilla'' or ''patch/<something>'' if the
patch depends on another patch.

The following are the steps required to add a feature branch/patch:

# <pre>tg create patch/new-feature vanilla</pre> - or - <pre>tg create patch/new-stuff patch/<sometging></pre>
# Edit .topmsg and make the subject line be a short description, optionally add a longer description to the body
# <pre>git add .topmsg && git commit</pre>
# Edit files of your patch.

=== Viewing patch history ===

 git log --first-parent

Thank to --first-parent option, only changes made to the topic branch are displayed and not the changes of merged-in branches (upstream).