1 Date: Mon, 15 Aug 2005 12:17:41 -0700
2 From: tony.luck@intel.com
3 Subject: Some tutorial text (was git/cogito workshop/bof at linuxconf au?)
4 Abstract: In this article, Tony Luck discusses how he uses GIT
5 as a Linux subsystem maintainer.
7 Here's something that I've been putting together on how I'm using
8 GIT as a Linux subsystem maintainer.
12 Last updated w.r.t. GIT 0.99.9f
14 Linux subsystem maintenance using GIT
15 -------------------------------------
17 My requirements here are to be able to create two public trees:
19 1) A "test" tree into which patches are initially placed so that they
20 can get some exposure when integrated with other ongoing development.
21 This tree is available to Andrew for pulling into -mm whenever he wants.
23 2) A "release" tree into which tested patches are moved for final
24 sanity checking, and as a vehicle to send them upstream to Linus
25 (by sending him a "please pull" request.)
27 Note that the period of time that each patch spends in the "test" tree
28 is dependent on the complexity of the change. Since GIT does not support
29 cherry picking, it is not practical to simply apply all patches to the
30 test tree and then pull to the release tree as that would leave trivial
31 patches blocked in the test tree waiting for complex changes to accumulate
32 enough test time to graduate.
34 Back in the BitKeeper days I achieved this by creating small forests of
35 temporary trees, one tree for each logical grouping of patches, and then
36 pulling changes from these trees first to the test tree, and then to the
37 release tree. At first I replicated this in GIT, but then I realised
38 that I could so this far more efficiently using branches inside a single
41 So here is the step-by-step guide how this all works for me.
43 First create your work tree by cloning Linus's public tree:
46 master.kernel.org:/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work
48 Change directory into the cloned tree you just created
52 Set up a remotes file so that you can fetch the latest from Linus' master
53 branch into a local branch named "linus":
55 $ cat > .git/remotes/linus
56 URL: master.kernel.org:/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
60 and create the linus branch:
64 The "linus" branch will be used to track the upstream kernel. To update it,
69 you can do this frequently (and it should be safe to do so with pending
70 work in your tree, but perhaps not if you are in mid-merge).
72 If you need to keep track of other public trees, you can add remote branches
76 $ cat > .git/remotes/another
77 URL: ... insert URL here ...
78 Pull: name-of-branch-in-this-remote-tree:another
85 Now create the branches in which you are going to work, these start
86 out at the current tip of the linus branch.
88 $ git branch test linus
89 $ git branch release linus
91 These can be easily kept up to date by merging from the "linus" branch:
93 $ git checkout test && git merge "Auto-update from upstream" test linus
94 $ git checkout release && git merge "Auto-update from upstream" release linus
96 Set up so that you can push upstream to your public tree (you need to
97 log-in to the remote system and create an empty tree there before the
100 $ cat > .git/remotes/mytree
101 URL: master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
106 and the push both the test and release trees using:
110 or push just one of the test and release branches using:
112 $ git push mytree test
114 $ git push mytree release
116 Now to apply some patches from the community. Think of a short
117 snappy name for a branch to hold this patch (or related group of
118 patches), and create a new branch from the current tip of the
121 $ git checkout -b speed-up-spinlocks linus
123 Now you apply the patch(es), run some tests, and commit the change(s). If
124 the patch is a multi-part series, then you should apply each as a separate
125 commit to this branch.
127 $ ... patch ... test ... commit [ ... patch ... test ... commit ]*
129 When you are happy with the state of this change, you can pull it into the
130 "test" branch in preparation to make it public:
132 $ git checkout test && git merge "Pull speed-up-spinlock changes" test speed-up-spinlocks
134 It is unlikely that you would have any conflicts here ... but you might if you
135 spent a while on this step and had also pulled new versions from upstream.
137 Some time later when enough time has passed and testing done, you can pull the
138 same branch into the "release" tree ready to go upstream. This is where you
139 see the value of keeping each patch (or patch series) in its own branch. It
140 means that the patches can be moved into the "release" tree in any order.
142 $ git checkout release && git merge "Pull speed-up-spinlock changes" release speed-up-spinlocks
144 After a while, you will have a number of branches, and despite the
145 well chosen names you picked for each of them, you may forget what
146 they are for, or what status they are in. To get a reminder of what
147 changes are in a specific branch, use:
149 $ git-whatchanged branchname ^linus | git-shortlog
151 To see whether it has already been merged into the test or release branches
154 $ git-rev-list branchname ^test
156 $ git-rev-list branchname ^release
158 [If this branch has not yet been merged you will see a set of SHA1 values
159 for the commits, if it has been merged, then there will be no output]
161 Once a patch completes the great cycle (moving from test to release, then
162 pulled by Linus, and finally coming back into your local "linus" branch)
163 the branch for this change is no longer needed. You detect this when the
166 $ git-rev-list branchname ^linus
168 is empty. At this point the branch can be deleted:
170 $ git branch -d branchname
172 Some changes are so trivial that it is not necessary to create a separate
173 branch and then merge into each of the test and release branches. For
174 these changes, just apply directly to the "release" branch, and then
175 merge that into the "test" branch.
177 To create diffstat and shortlog summaries of changes to include in a "please
178 pull" request to Linus you can use:
180 $ git-whatchanged -p release ^linus | diffstat -p1
182 $ git-whatchanged release ^linus | git-shortlog
185 Here are some of the scripts that I use to simplify all this even further.
187 ==== update script ====
188 # Update a branch in my GIT tree. If the branch to be updated
189 # is "linus", then pull from kernel.org. Otherwise merge local
190 # linus branch into test|release branch
194 git checkout $1 && git merge "Auto-update from upstream" $1 linus
197 before=$(cat .git/refs/heads/linus)
199 after=$(cat .git/refs/heads/linus)
200 if [ $before != $after ]
202 git-whatchanged $after ^$before | git-shortlog
206 echo "Usage: $0 linus|test|release" 1>&2
211 ==== merge script ====
212 # Merge a branch into either the test or release branch
218 echo "Usage: $pname branch test|release" 1>&2
222 if [ ! -f .git/refs/heads/"$1" ]
224 echo "Can't see branch <$1>" 1>&2
230 if [ $(git-rev-list $1 ^$2 | wc -c) -eq 0 ]
232 echo $1 already merged into $2 1>&2
235 git checkout $2 && git merge "Pull $1 into $2 branch" $2 $1
242 ==== status script ====
243 # report on status of my ia64 GIT tree
247 restore=$(tput setab 9)
249 if [ `git-rev-list release ^test | wc -c` -gt 0 ]
251 echo $rb Warning: commits in release that are not in test $restore
252 git-whatchanged release ^test
255 for branch in `ls .git/refs/heads`
257 if [ $branch = linus -o $branch = test -o $branch = release ]
262 echo -n $gb ======= $branch ====== $restore " "
264 for ref in test release linus
266 if [ `git-rev-list $branch ^$ref | wc -c` -gt 0 ]
268 status=$status${ref:0:1}
273 echo $rb Need to pull into test $restore
279 echo "Waiting for linus"
282 echo $rb All done $restore
285 echo $rb "<$status>" $restore
288 git-whatchanged $branch ^linus | git-shortlog