@matheusbsbs / matheus-bagliano / commits / f948dd8992
Fork 0

Documentation: add manpage about workflows

This attempts to make a manpage about workflows that is both handy to point people at it and as a beginner's introduction. Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Thomas Rast committed Oct 19, 2008 at 17:20 UTC f948dd899210e5a51cd716245affb7c121bf8791
2 files changed +365 -1
Documentation/Makefile
+1 -1
@@ -6,7 +6,7 @@ MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
6 gitrepository-layout.txt
7 MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
8 gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \
9 - gitdiffcore.txt
9 + gitdiffcore.txt gitworkflows.txt
10
11 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
12 MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
Documentation/gitworkflows.txt new
+364
@@ -0,0 +1,364 @@
1 +gitworkflows(7)
2 +===============
3 +
4 +NAME
5 +----
6 +gitworkflows - An overview of recommended workflows with git
7 +
8 +SYNOPSIS
9 +--------
10 +git *
11 +
12 +
13 +DESCRIPTION
14 +-----------
15 +
16 +This document attempts to write down and motivate some of the workflow
17 +elements used for `git.git` itself. Many ideas apply in general,
18 +though the full workflow is rarely required for smaller projects with
19 +fewer people involved.
20 +
21 +We formulate a set of 'rules' for quick reference, while the prose
22 +tries to motivate each of them. Do not always take them literally;
23 +you should value good reasons for your actions higher than manpages
24 +such as this one.
25 +
26 +
27 +SEPARATE CHANGES
28 +----------------
29 +
30 +As a general rule, you should try to split your changes into small
31 +logical steps, and commit each of them. They should be consistent,
32 +working independently of any later commits, pass the test suite, etc.
33 +This makes the review process much easier, and the history much more
34 +useful for later inspection and analysis, for example with
35 +linkgit:git-blame[1] and linkgit:git-bisect[1].
36 +
37 +To achieve this, try to split your work into small steps from the very
38 +beginning. It is always easier to squash a few commits together than
39 +to split one big commit into several. Don't be afraid of making too
40 +small or imperfect steps along the way. You can always go back later
41 +and edit the commits with `git rebase \--interactive` before you
42 +publish them. You can use `git stash save \--keep-index` to run the
43 +test suite independent of other uncommitted changes; see the EXAMPLES
44 +section of linkgit:git-stash[1].
45 +
46 +
47 +MANAGING BRANCHES
48 +-----------------
49 +
50 +There are two main tools that can be used to include changes from one
51 +branch on another: linkgit:git-merge[1] and
52 +linkgit:git-cherry-pick[1].
53 +
54 +Merges have many advantages, so we try to solve as many problems as
55 +possible with merges alone. Cherry-picking is still occasionally
56 +useful; see "Merging upwards" below for an example.
57 +
58 +Most importantly, merging works at the branch level, while
59 +cherry-picking works at the commit level. This means that a merge can
60 +carry over the changes from 1, 10, or 1000 commits with equal ease,
61 +which in turn means the workflow scales much better to a large number
62 +of contributors (and contributions). Merges are also easier to
63 +understand because a merge commit is a "promise" that all changes from
64 +all its parents are now included.
65 +
66 +There is a tradeoff of course: merges require a more careful branch
67 +management. The following subsections discuss the important points.
68 +
69 +
70 +Graduation
71 +~~~~~~~~~~
72 +
73 +As a given feature goes from experimental to stable, it also
74 +"graduates" between the corresponding branches of the software.
75 +`git.git` uses the following 'integration branches':
76 +
77 +* 'maint' tracks the commits that should go into the next "maintenance
78 + release", i.e., update of the last released stable version;
79 +
80 +* 'master' tracks the commits that should go into the next release;
81 +
82 +* 'next' is intended as a testing branch for topics being tested for
83 + stability for master.
84 +
85 +There is a fourth official branch that is used slightly differently:
86 +
87 +* 'pu' (proposed updates) is an integration branch for things that are
88 + not quite ready for inclusion yet (see "Integration Branches"
89 + below).
90 +
91 +Each of the four branches is usually a direct descendant of the one
92 +above it.
93 +
94 +Conceptually, the feature enters at an unstable branch (usually 'next'
95 +or 'pu'), and "graduates" to 'master' for the next release once it is
96 +considered stable enough.
97 +
98 +
99 +Merging upwards
100 +~~~~~~~~~~~~~~~
101 +
102 +The "downwards graduation" discussed above cannot be done by actually
103 +merging downwards, however, since that would merge 'all' changes on
104 +the unstable branch into the stable one. Hence the following:
105 +
106 +.Merge upwards
107 +[caption="Rule: "]
108 +=====================================
109 +Always commit your fixes to the oldest supported branch that require
110 +them. Then (periodically) merge the integration branches upwards into each
111 +other.
112 +=====================================
113 +
114 +This gives a very controlled flow of fixes. If you notice that you
115 +have applied a fix to e.g. 'master' that is also required in 'maint',
116 +you will need to cherry-pick it (using linkgit:git-cherry-pick[1])
117 +downwards. This will happen a few times and is nothing to worry about
118 +unless you do it very frequently.
119 +
120 +
121 +Topic branches
122 +~~~~~~~~~~~~~~
123 +
124 +Any nontrivial feature will require several patches to implement, and
125 +may get extra bugfixes or improvements during its lifetime.
126 +
127 +Committing everything directly on the integration branches leads to many
128 +problems: Bad commits cannot be undone, so they must be reverted one
129 +by one, which creates confusing histories and further error potential
130 +when you forget to revert part of a group of changes. Working in
131 +parallel mixes up the changes, creating further confusion.
132 +
133 +Use of "topic branches" solves these problems. The name is pretty
134 +self explanatory, with a caveat that comes from the "merge upwards"
135 +rule above:
136 +
137 +.Topic branches
138 +[caption="Rule: "]
139 +=====================================
140 +Make a side branch for every topic (feature, bugfix, ...). Fork it off
141 +at the oldest integration branch that you will eventually want to merge it
142 +into.
143 +=====================================
144 +
145 +Many things can then be done very naturally:
146 +
147 +* To get the feature/bugfix into an integration branch, simply merge
148 + it. If the topic has evolved further in the meantime, merge again.
149 + (Note that you do not necessarily have to merge it to the oldest
150 + integration branch first. For example, you can first merge a bugfix
151 + to 'next', give it some testing time, and merge to 'maint' when you
152 + know it is stable.)
153 +
154 +* If you find you need new features from the branch 'other' to continue
155 + working on your topic, merge 'other' to 'topic'. (However, do not
156 + do this "just habitually", see below.)
157 +
158 +* If you find you forked off the wrong branch and want to move it
159 + "back in time", use linkgit:git-rebase[1].
160 +
161 +Note that the last point clashes with the other two: a topic that has
162 +been merged elsewhere should not be rebased. See the section on
163 +RECOVERING FROM UPSTREAM REBASE in linkgit:git-rebase[1].
164 +
165 +We should point out that "habitually" (regularly for no real reason)
166 +merging an integration branch into your topics -- and by extension,
167 +merging anything upstream into anything downstream on a regular basis
168 +-- is frowned upon:
169 +
170 +.Merge to downstream only at well-defined points
171 +[caption="Rule: "]
172 +=====================================
173 +Do not merge to downstream except with a good reason: upstream API
174 +changes affect your branch; your branch no longer merges to upstream
175 +cleanly; etc.
176 +=====================================
177 +
178 +Otherwise, the topic that was merged to suddenly contains more than a
179 +single (well-separated) change. The many resulting small merges will
180 +greatly clutter up history. Anyone who later investigates the history
181 +of a file will have to find out whether that merge affected the topic
182 +in development. An upstream might even inadvertently be merged into a
183 +"more stable" branch. And so on.
184 +
185 +
186 +Throw-away integration
187 +~~~~~~~~~~~~~~~~~~~~~~
188 +
189 +If you followed the last paragraph, you will now have many small topic
190 +branches, and occasionally wonder how they interact. Perhaps the
191 +result of merging them does not even work? But on the other hand, we
192 +want to avoid merging them anywhere "stable" because such merges
193 +cannot easily be undone.
194 +
195 +The solution, of course, is to make a merge that we can undo: merge
196 +into a throw-away branch.
197 +
198 +.Throw-away integration branches
199 +[caption="Rule: "]
200 +=====================================
201 +To test the interaction of several topics, merge them into a
202 +throw-away branch. You must never base any work on such a branch!
203 +=====================================
204 +
205 +If you make it (very) clear that this branch is going to be deleted
206 +right after the testing, you can even publish this branch, for example
207 +to give the testers a chance to work with it, or other developers a
208 +chance to see if their in-progress work will be compatible. `git.git`
209 +has such an official throw-away integration branch called 'pu'.
210 +
211 +
212 +DISTRIBUTED WORKFLOWS
213 +---------------------
214 +
215 +After the last section, you should know how to manage topics. In
216 +general, you will not be the only person working on the project, so
217 +you will have to share your work.
218 +
219 +Roughly speaking, there are two important workflows: merge and patch.
220 +The important difference is that the merge workflow can propagate full
221 +history, including merges, while patches cannot. Both workflows can
222 +be used in parallel: in `git.git`, only subsystem maintainers use
223 +the merge workflow, while everyone else sends patches.
224 +
225 +Note that the maintainer(s) may impose restrictions, such as
226 +"Signed-off-by" requirements, that all commits/patches submitted for
227 +inclusion must adhere to. Consult your project's documentation for
228 +more information.
229 +
230 +
231 +Merge workflow
232 +~~~~~~~~~~~~~~
233 +
234 +The merge workflow works by copying branches between upstream and
235 +downstream. Upstream can merge contributions into the official
236 +history; downstream base their work on the official history.
237 +
238 +There are three main tools that can be used for this:
239 +
240 +* linkgit:git-push[1] copies your branches to a remote repository,
241 + usually to one that can be read by all involved parties;
242 +
243 +* linkgit:git-fetch[1] that copies remote branches to your repository;
244 + and
245 +
246 +* linkgit:git-pull[1] that does fetch and merge in one go.
247 +
248 +Note the last point. Do 'not' use 'git-pull' unless you actually want
249 +to merge the remote branch.
250 +
251 +Getting changes out is easy:
252 +
253 +.Push/pull: Publishing branches/topics
254 +[caption="Recipe: "]
255 +=====================================
256 +`git push <remote> <branch>` and tell everyone where they can fetch
257 +from.
258 +=====================================
259 +
260 +You will still have to tell people by other means, such as mail. (Git
261 +provides the linkgit:request-pull[1] to send preformatted pull
262 +requests to upstream maintainers to simplify this task.)
263 +
264 +If you just want to get the newest copies of the integration branches,
265 +staying up to date is easy too:
266 +
267 +.Push/pull: Staying up to date
268 +[caption="Recipe: "]
269 +=====================================
270 +Use `git fetch <remote>` or `git remote update` to stay up to date.
271 +=====================================
272 +
273 +Then simply fork your topic branches from the stable remotes as
274 +explained earlier.
275 +
276 +If you are a maintainer and would like to merge other people's topic
277 +branches to the integration branches, they will typically send a
278 +request to do so by mail. Such a request looks like
279 +
280 +-------------------------------------
281 +Please pull from
282 + <url> <branch>
283 +-------------------------------------
284 +
285 +In that case, 'git-pull' can do the fetch and merge in one go, as
286 +follows.
287 +
288 +.Push/pull: Merging remote topics
289 +[caption="Recipe: "]
290 +=====================================
291 +`git pull <url> <branch>`
292 +=====================================
293 +
294 +Occasionally, the maintainer may get merge conflicts when he tries to
295 +pull changes from downstream. In this case, he can ask downstream to
296 +do the merge and resolve the conflicts themselves (perhaps they will
297 +know better how to resolve them). It is one of the rare cases where
298 +downstream 'should' merge from upstream.
299 +
300 +
301 +Patch workflow
302 +~~~~~~~~~~~~~~
303 +
304 +If you are a contributor that sends changes upstream in the form of
305 +emails, you should use topic branches as usual (see above). Then use
306 +linkgit:git-format-patch[1] to generate the corresponding emails
307 +(highly recommended over manually formatting them because it makes the
308 +maintainer's life easier).
309 +
310 +.format-patch/am: Publishing branches/topics
311 +[caption="Recipe: "]
312 +=====================================
313 +* `git format-patch -M upstream..topic` to turn them into preformatted
314 + patch files
315 +* `git send-email --to=<recipient> <patches>`
316 +=====================================
317 +
318 +See the linkgit:git-format-patch[1] and linkgit:git-send-email[1]
319 +manpages for further usage notes.
320 +
321 +If the maintainer tells you that your patch no longer applies to the
322 +current upstream, you will have to rebase your topic (you cannot use a
323 +merge because you cannot format-patch merges):
324 +
325 +.format-patch/am: Keeping topics up to date
326 +[caption="Recipe: "]
327 +=====================================
328 +`git pull --rebase <url> <branch>`
329 +=====================================
330 +
331 +You can then fix the conflicts during the rebase. Presumably you have
332 +not published your topic other than by mail, so rebasing it is not a
333 +problem.
334 +
335 +If you receive such a patch series (as maintainer, or perhaps as a
336 +reader of the mailing list it was sent to), save the mails to files,
337 +create a new topic branch and use 'git-am' to import the commits:
338 +
339 +.format-patch/am: Importing patches
340 +[caption="Recipe: "]
341 +=====================================
342 +`git am < patch`
343 +=====================================
344 +
345 +One feature worth pointing out is the three-way merge, which can help
346 +if you get conflicts: `git am -3` will use index information contained
347 +in patches to figure out the merge base. See linkgit:git-am[1] for
348 +other options.
349 +
350 +
351 +SEE ALSO
352 +--------
353 +linkgit:gittutorial[7],
354 +linkgit:git-push[1],
355 +linkgit:git-pull[1],
356 +linkgit:git-merge[1],
357 +linkgit:git-rebase[1],
358 +linkgit:git-format-patch[1],
359 +linkgit:git-send-email[1],
360 +linkgit:git-am[1]
361 +
362 +GIT
363 +---
364 +Part of the linkgit:git[1] suite.