@matheusbsbs / matheus-bagliano / commits / 9e2163ea45
Fork 0

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]]