user-manual: move howto/using-topic-branches into manual
Move howto/using-topic-branches into the user manual as an example for the "sharing development" chapter. While we're at it, remove some discussion that's covered in earlier chapters, modernize somewhat (use separate-heads setup, remotes, replace "whatchanged" by "log", etc.), and replace syntax we'd need to explain by syntax we've already covered (e.g. old..new instead of new ^old). The result may not really describe what Tony Luck does any more.... Hope that's not annoying. Cc: Tony Luck <tony.luck@intel.com> Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
J. Bruce Fields committed
May 13, 2007 at 01:48 UTC
9e2163ea45b688e9de4744ebb9b01ea7e1ed8d56
2 files changed
+296
-297
Documentation/howto/using-topic-branches.txt
deleted
-296
@@ -1,296 +0,0 @@
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.
6
-
7
-Here's something that I've been putting together on how I'm using
8
-GIT as a Linux subsystem maintainer.
9
-
10
--Tony
11
-
12
-Last updated w.r.t. GIT 1.1
13
-
14
-Linux subsystem maintenance using GIT
15
--------------------------------------
16
-
17
-My requirements here are to be able to create two public trees:
18
-
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.
22
-
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.)
26
-
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.
33
-
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
39
-GIT repository.
40
-
41
-So here is the step-by-step guide how this all works for me.
42
-
43
-First create your work tree by cloning Linus's public tree:
44
-
45
- $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work
46
-
47
-Change directory into the cloned tree you just created
48
-
49
- $ cd work
50
-
51
-Set up a remotes file so that you can fetch the latest from Linus' master
52
-branch into a local branch named "linus":
53
-
54
- $ cat > .git/remotes/linus
55
- URL: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
56
- Pull: master:linus
57
- ^D
58
-
59
-and create the linus branch:
60
-
61
- $ git branch linus
62
-
63
-The "linus" branch will be used to track the upstream kernel. To update it,
64
-you simply run:
65
-
66
- $ git fetch linus
67
-
68
-you can do this frequently (and it should be safe to do so with pending
69
-work in your tree, but perhaps not if you are in mid-merge).
70
-
71
-If you need to keep track of other public trees, you can add remote branches
72
-for them too:
73
-
74
- $ git branch another
75
- $ cat > .git/remotes/another
76
- URL: ... insert URL here ...
77
- Pull: name-of-branch-in-this-remote-tree:another
78
- ^D
79
-
80
-and run:
81
-
82
- $ git fetch another
83
-
84
-Now create the branches in which you are going to work, these start
85
-out at the current tip of the linus branch.
86
-
87
- $ git branch test linus
88
- $ git branch release linus
89
-
90
-These can be easily kept up to date by merging from the "linus" branch:
91
-
92
- $ git checkout test && git merge "Auto-update from upstream" test linus
93
- $ git checkout release && git merge "Auto-update from upstream" release linus
94
-
95
-Important note! If you have any local changes in these branches, then
96
-this merge will create a commit object in the history (with no local
97
-changes git will simply do a "Fast forward" merge). Many people dislike
98
-the "noise" that this creates in the Linux history, so you should avoid
99
-doing this capriciously in the "release" branch, as these noisy commits
100
-will become part of the permanent history when you ask Linus to pull
101
-from the release branch.
102
-
103
-Set up so that you can push upstream to your public tree (you need to
104
-log-in to the remote system and create an empty tree there before the
105
-first push).
106
-
107
- $ cat > .git/remotes/mytree
108
- URL: master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
109
- Push: release
110
- Push: test
111
- ^D
112
-
113
-and the push both the test and release trees using:
114
-
115
- $ git push mytree
116
-
117
-or push just one of the test and release branches using:
118
-
119
- $ git push mytree test
120
-or
121
- $ git push mytree release
122
-
123
-Now to apply some patches from the community. Think of a short
124
-snappy name for a branch to hold this patch (or related group of
125
-patches), and create a new branch from the current tip of the
126
-linus branch:
127
-
128
- $ git checkout -b speed-up-spinlocks linus
129
-
130
-Now you apply the patch(es), run some tests, and commit the change(s). If
131
-the patch is a multi-part series, then you should apply each as a separate
132
-commit to this branch.
133
-
134
- $ ... patch ... test ... commit [ ... patch ... test ... commit ]*
135
-
136
-When you are happy with the state of this change, you can pull it into the
137
-"test" branch in preparation to make it public:
138
-
139
- $ git checkout test && git merge "Pull speed-up-spinlock changes" test speed-up-spinlocks
140
-
141
-It is unlikely that you would have any conflicts here ... but you might if you
142
-spent a while on this step and had also pulled new versions from upstream.
143
-
144
-Some time later when enough time has passed and testing done, you can pull the
145
-same branch into the "release" tree ready to go upstream. This is where you
146
-see the value of keeping each patch (or patch series) in its own branch. It
147
-means that the patches can be moved into the "release" tree in any order.
148
-
149
- $ git checkout release && git merge "Pull speed-up-spinlock changes" release speed-up-spinlocks
150
-
151
-After a while, you will have a number of branches, and despite the
152
-well chosen names you picked for each of them, you may forget what
153
-they are for, or what status they are in. To get a reminder of what
154
-changes are in a specific branch, use:
155
-
156
- $ git-whatchanged branchname ^linus | git-shortlog
157
-
158
-To see whether it has already been merged into the test or release branches
159
-use:
160
-
161
- $ git-rev-list branchname ^test
162
-or
163
- $ git-rev-list branchname ^release
164
-
165
-[If this branch has not yet been merged you will see a set of SHA1 values
166
-for the commits, if it has been merged, then there will be no output]
167
-
168
-Once a patch completes the great cycle (moving from test to release, then
169
-pulled by Linus, and finally coming back into your local "linus" branch)
170
-the branch for this change is no longer needed. You detect this when the
171
-output from:
172
-
173
- $ git-rev-list branchname ^linus
174
-
175
-is empty. At this point the branch can be deleted:
176
-
177
- $ git branch -d branchname
178
-
179
-Some changes are so trivial that it is not necessary to create a separate
180
-branch and then merge into each of the test and release branches. For
181
-these changes, just apply directly to the "release" branch, and then
182
-merge that into the "test" branch.
183
-
184
-To create diffstat and shortlog summaries of changes to include in a "please
185
-pull" request to Linus you can use:
186
-
187
- $ git-whatchanged -p release ^linus | diffstat -p1
188
-and
189
- $ git-whatchanged release ^linus | git-shortlog
190
-
191
-
192
-Here are some of the scripts that I use to simplify all this even further.
193
-
194
-==== update script ====
195
-# Update a branch in my GIT tree. If the branch to be updated
196
-# is "linus", then pull from kernel.org. Otherwise merge local
197
-# linus branch into test|release branch
198
-
199
-case "$1" in
200
-test|release)
201
- git checkout $1 && git merge "Auto-update from upstream" $1 linus
202
- ;;
203
-linus)
204
- before=$(cat .git/refs/heads/linus)
205
- git fetch linus
206
- after=$(cat .git/refs/heads/linus)
207
- if [ $before != $after ]
208
- then
209
- git-whatchanged $after ^$before | git-shortlog
210
- fi
211
- ;;
212
-*)
213
- echo "Usage: $0 linus|test|release" 1>&2
214
- exit 1
215
- ;;
216
-esac
217
-
218
-==== merge script ====
219
-# Merge a branch into either the test or release branch
220
-
221
-pname=$0
222
-
223
-usage()
224
-{
225
- echo "Usage: $pname branch test|release" 1>&2
226
- exit 1
227
-}
228
-
229
-if [ ! -f .git/refs/heads/"$1" ]
230
-then
231
- echo "Can't see branch <$1>" 1>&2
232
- usage
233
-fi
234
-
235
-case "$2" in
236
-test|release)
237
- if [ $(git-rev-list $1 ^$2 | wc -c) -eq 0 ]
238
- then
239
- echo $1 already merged into $2 1>&2
240
- exit 1
241
- fi
242
- git checkout $2 && git merge "Pull $1 into $2 branch" $2 $1
243
- ;;
244
-*)
245
- usage
246
- ;;
247
-esac
248
-
249
-==== status script ====
250
-# report on status of my ia64 GIT tree
251
-
252
-gb=$(tput setab 2)
253
-rb=$(tput setab 1)
254
-restore=$(tput setab 9)
255
-
256
-if [ `git-rev-list release ^test | wc -c` -gt 0 ]
257
-then
258
- echo $rb Warning: commits in release that are not in test $restore
259
- git-whatchanged release ^test
260
-fi
261
-
262
-for branch in `ls .git/refs/heads`
263
-do
264
- if [ $branch = linus -o $branch = test -o $branch = release ]
265
- then
266
- continue
267
- fi
268
-
269
- echo -n $gb ======= $branch ====== $restore " "
270
- status=
271
- for ref in test release linus
272
- do
273
- if [ `git-rev-list $branch ^$ref | wc -c` -gt 0 ]
274
- then
275
- status=$status${ref:0:1}
276
- fi
277
- done
278
- case $status in
279
- trl)
280
- echo $rb Need to pull into test $restore
281
- ;;
282
- rl)
283
- echo "In test"
284
- ;;
285
- l)
286
- echo "Waiting for linus"
287
- ;;
288
- "")
289
- echo $rb All done $restore
290
- ;;
291
- *)
292
- echo $rb "<$status>" $restore
293
- ;;
294
- esac
295
- git-whatchanged $branch ^linus | git-shortlog
296
-done
Documentation/user-manual.txt
+296
-1
@@ -1789,7 +1789,302 @@ gitweb/INSTALL in the git source tree for instructions on setting it up.
1789
Examples
1790
--------
1791
1792
-TODO: topic branches, typical roles as in everyday.txt, ?
1792
+[[maintaining-topic-branches]]
1793
+Maintaining topic branches for a Linux subsystem maintainer
1794
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1795
+
1796
+This describes how Tony Luck uses git in his role as maintainer of the
1797
+IA64 architecture for the Linux kernel.
1798
+
1799
+He uses two public branches:
1800
+
1801
+ - A "test" tree into which patches are initially placed so that they
1802
+ can get some exposure when integrated with other ongoing development.
1803
+ This tree is available to Andrew for pulling into -mm whenever he
1804
+ wants.
1805
+
1806
+ - A "release" tree into which tested patches are moved for final sanity
1807
+ checking, and as a vehicle to send them upstream to Linus (by sending
1808
+ him a "please pull" request.)
1809
+
1810
+He also uses a set of temporary branches ("topic branches"), each
1811
+containing a logical grouping of patches.
1812
+
1813
+To set this up, first create your work tree by cloning Linus's public
1814
+tree:
1815
+
1816
+-------------------------------------------------
1817
+$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work
1818
+$ cd work
1819
+-------------------------------------------------
1820
+
1821
+Linus's tree will be stored in the remote branch named origin/master,
1822
+and can be updated using gitlink:git-fetch[1]; you can track other
1823
+public trees using gitlink:git-remote[1] to set up a "remote" and
1824
+git-fetch[1] to keep them up-to-date; see <<repositories-and-branches>>.
1825
+
1826
+Now create the branches in which you are going to work; these start out
1827
+at the current tip of origin/master branch, and should be set up (using
1828
+the --track option to gitlink:git-branch[1]) to merge changes in from
1829
+Linus by default.
1830
+
1831
+-------------------------------------------------
1832
+$ git branch --track test origin/master
1833
+$ git branch --track release origin/master
1834
+-------------------------------------------------
1835
+
1836
+These can be easily kept up to date using gitlink:git-pull[1]
1837
+
1838
+-------------------------------------------------
1839
+$ git checkout test && git pull
1840
+$ git checkout release && git pull
1841
+-------------------------------------------------
1842
+
1843
+Important note! If you have any local changes in these branches, then
1844
+this merge will create a commit object in the history (with no local
1845
+changes git will simply do a "Fast forward" merge). Many people dislike
1846
+the "noise" that this creates in the Linux history, so you should avoid
1847
+doing this capriciously in the "release" branch, as these noisy commits
1848
+will become part of the permanent history when you ask Linus to pull
1849
+from the release branch.
1850
+
1851
+A few configuration variables (see gitlink:git-config[1]) can
1852
+make it easy to push both branches to your public tree. (See
1853
+<<setting-up-a-public-repository>>.)
1854
+
1855
+-------------------------------------------------
1856
+$ cat >> .git/config <<EOF
1857
+[remote "mytree"]
1858
+ url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
1859
+ push = release
1860
+ push = test
1861
+EOF
1862
+-------------------------------------------------
1863
+
1864
+Then you can push both the test and release trees using
1865
+gitlink:git-push[1]:
1866
+
1867
+-------------------------------------------------
1868
+$ git push mytree
1869
+-------------------------------------------------
1870
+
1871
+or push just one of the test and release branches using:
1872
+
1873
+-------------------------------------------------
1874
+$ git push mytree test
1875
+-------------------------------------------------
1876
+
1877
+or
1878
+
1879
+-------------------------------------------------
1880
+$ git push mytree release
1881
+-------------------------------------------------
1882
+
1883
+Now to apply some patches from the community. Think of a short
1884
+snappy name for a branch to hold this patch (or related group of
1885
+patches), and create a new branch from the current tip of Linus's
1886
+branch:
1887
+
1888
+-------------------------------------------------
1889
+$ git checkout -b speed-up-spinlocks origin
1890
+-------------------------------------------------
1891
+
1892
+Now you apply the patch(es), run some tests, and commit the change(s). If
1893
+the patch is a multi-part series, then you should apply each as a separate
1894
+commit to this branch.
1895
+
1896
+-------------------------------------------------
1897
+$ ... patch ... test ... commit [ ... patch ... test ... commit ]*
1898
+-------------------------------------------------
1899
+
1900
+When you are happy with the state of this change, you can pull it into the
1901
+"test" branch in preparation to make it public:
1902
+
1903
+-------------------------------------------------
1904
+$ git checkout test && git pull . speed-up-spinlocks
1905
+-------------------------------------------------
1906
+
1907
+It is unlikely that you would have any conflicts here ... but you might if you
1908
+spent a while on this step and had also pulled new versions from upstream.
1909
+
1910
+Some time later when enough time has passed and testing done, you can pull the
1911
+same branch into the "release" tree ready to go upstream. This is where you
1912
+see the value of keeping each patch (or patch series) in its own branch. It
1913
+means that the patches can be moved into the "release" tree in any order.
1914
+
1915
+-------------------------------------------------
1916
+$ git checkout release && git pull . speed-up-spinlocks
1917
+-------------------------------------------------
1918
+
1919
+After a while, you will have a number of branches, and despite the
1920
+well chosen names you picked for each of them, you may forget what
1921
+they are for, or what status they are in. To get a reminder of what
1922
+changes are in a specific branch, use:
1923
+
1924
+-------------------------------------------------
1925
+$ git log linux..branchname | git-shortlog
1926
+-------------------------------------------------
1927
+
1928
+To see whether it has already been merged into the test or release branches
1929
+use:
1930
+
1931
+-------------------------------------------------
1932
+$ git log test..branchname
1933
+-------------------------------------------------
1934
+
1935
+or
1936
+
1937
+-------------------------------------------------
1938
+$ git log release..branchname
1939
+-------------------------------------------------
1940
+
1941
+(If this branch has not yet been merged you will see some log entries.
1942
+If it has been merged, then there will be no output.)
1943
+
1944
+Once a patch completes the great cycle (moving from test to release,
1945
+then pulled by Linus, and finally coming back into your local
1946
+"origin/master" branch) the branch for this change is no longer needed.
1947
+You detect this when the output from:
1948
+
1949
+-------------------------------------------------
1950
+$ git log origin..branchname
1951
+-------------------------------------------------
1952
+
1953
+is empty. At this point the branch can be deleted:
1954
+
1955
+-------------------------------------------------
1956
+$ git branch -d branchname
1957
+-------------------------------------------------
1958
+
1959
+Some changes are so trivial that it is not necessary to create a separate
1960
+branch and then merge into each of the test and release branches. For
1961
+these changes, just apply directly to the "release" branch, and then
1962
+merge that into the "test" branch.
1963
+
1964
+To create diffstat and shortlog summaries of changes to include in a "please
1965
+pull" request to Linus you can use:
1966
+
1967
+-------------------------------------------------
1968
+$ git diff --stat origin..release
1969
+-------------------------------------------------
1970
+
1971
+and
1972
+
1973
+-------------------------------------------------
1974
+$ git log -p origin..release | git shortlog
1975
+-------------------------------------------------
1976
+
1977
+Here are some of the scripts that simplify all this even further.
1978
+
1979
+-------------------------------------------------
1980
+==== update script ====
1981
+# Update a branch in my GIT tree. If the branch to be updated
1982
+# is origin, then pull from kernel.org. Otherwise merge
1983
+# origin/master branch into test|release branch
1984
+
1985
+case "$1" in
1986
+test|release)
1987
+ git checkout $1 && git pull . origin
1988
+ ;;
1989
+origin)
1990
+ before=$(cat .git/refs/remotes/origin/master)
1991
+ git fetch origin
1992
+ after=$(cat .git/refs/remotes/origin/master)
1993
+ if [ $before != $after ]
1994
+ then
1995
+ git log $before..$after | git shortlog
1996
+ fi
1997
+ ;;
1998
+*)
1999
+ echo "Usage: $0 origin|test|release" 1>&2
2000
+ exit 1
2001
+ ;;
2002
+esac
2003
+-------------------------------------------------
2004
+
2005
+-------------------------------------------------
2006
+==== merge script ====
2007
+# Merge a branch into either the test or release branch
2008
+
2009
+pname=$0
2010
+
2011
+usage()
2012
+{
2013
+ echo "Usage: $pname branch test|release" 1>&2
2014
+ exit 1
2015
+}
2016
+
2017
+if [ ! -f .git/refs/heads/"$1" ]
2018
+then
2019
+ echo "Can't see branch <$1>" 1>&2
2020
+ usage
2021
+fi
2022
+
2023
+case "$2" in
2024
+test|release)
2025
+ if [ $(git log $2..$1 | wc -c) -eq 0 ]
2026
+ then
2027
+ echo $1 already merged into $2 1>&2
2028
+ exit 1
2029
+ fi
2030
+ git checkout $2 && git pull . $1
2031
+ ;;
2032
+*)
2033
+ usage
2034
+ ;;
2035
+esac
2036
+-------------------------------------------------
2037
+
2038
+-------------------------------------------------
2039
+==== status script ====
2040
+# report on status of my ia64 GIT tree
2041
+
2042
+gb=$(tput setab 2)
2043
+rb=$(tput setab 1)
2044
+restore=$(tput setab 9)
2045
+
2046
+if [ `git rev-list test..release | wc -c` -gt 0 ]
2047
+then
2048
+ echo $rb Warning: commits in release that are not in test $restore
2049
+ git log test..release
2050
+fi
2051
+
2052
+for branch in `ls .git/refs/heads`
2053
+do
2054
+ if [ $branch = test -o $branch = release ]
2055
+ then
2056
+ continue
2057
+ fi
2058
+
2059
+ echo -n $gb ======= $branch ====== $restore " "
2060
+ status=
2061
+ for ref in test release origin/master
2062
+ do
2063
+ if [ `git rev-list $ref..$branch | wc -c` -gt 0 ]
2064
+ then
2065
+ status=$status${ref:0:1}
2066
+ fi
2067
+ done
2068
+ case $status in
2069
+ trl)
2070
+ echo $rb Need to pull into test $restore
2071
+ ;;
2072
+ rl)
2073
+ echo "In test"
2074
+ ;;
2075
+ l)
2076
+ echo "Waiting for linus"
2077
+ ;;
2078
+ "")
2079
+ echo $rb All done $restore
2080
+ ;;
2081
+ *)
2082
+ echo $rb "<$status>" $restore
2083
+ ;;
2084
+ esac
2085
+ git log origin/master..$branch | git shortlog
2086
+done
2087
+-------------------------------------------------
2088
2089
2090
[[cleaning-up-history]]