]>
Commit | Line | Data |
---|---|---|
f948dd89 TR |
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 | ||
382e5431 RG |
212 | Branch management for a release |
213 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
214 | ||
215 | Assuming you are using the merge approach discussed above, when you | |
216 | are releasing your project you will need to do some additional branch | |
217 | management work. | |
218 | ||
219 | A feature release is created from the 'master' branch, since 'master' | |
220 | tracks the commits that should go into the next feature release. | |
221 | ||
222 | The 'master' branch is supposed to be a superset of 'maint'. If this | |
223 | condition does not hold, then 'maint' contains some commits that | |
224 | are not included on 'master'. The fixes represented by those commits | |
225 | will therefore not be included in your feature release. | |
226 | ||
227 | To verify that 'master' is indeed a superset of 'maint', use git log: | |
228 | ||
229 | .Verify 'master' is a superset of 'maint' | |
230 | [caption="Recipe: "] | |
231 | ===================================== | |
c8e1c3d3 | 232 | `git log master..maint` |
382e5431 RG |
233 | ===================================== |
234 | ||
235 | This command should not list any commits. Otherwise, check out | |
236 | 'master' and merge 'maint' into it. | |
237 | ||
238 | Now you can proceed with the creation of the feature release. Apply a | |
239 | tag to the tip of 'master' indicating the release version: | |
240 | ||
241 | .Release tagging | |
242 | [caption="Recipe: "] | |
243 | ===================================== | |
244 | `git tag -s -m "GIT X.Y.Z" vX.Y.Z master` | |
245 | ===================================== | |
246 | ||
247 | You need to push the new tag to a public git server (see | |
248 | "DISTRIBUTED WORKFLOWS" below). This makes the tag available to | |
249 | others tracking your project. The push could also trigger a | |
250 | post-update hook to perform release-related items such as building | |
251 | release tarballs and preformatted documentation pages. | |
252 | ||
253 | Similarly, for a maintenance release, 'maint' is tracking the commits | |
254 | to be released. Therefore, in the steps above simply tag and push | |
255 | 'maint' rather than 'master'. | |
256 | ||
257 | ||
258 | Maintenance branch management after a feature release | |
259 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
260 | ||
261 | After a feature release, you need to manage your maintenance branches. | |
262 | ||
263 | First, if you wish to continue to release maintenance fixes for the | |
264 | feature release made before the recent one, then you must create | |
265 | another branch to track commits for that previous release. | |
266 | ||
267 | To do this, the current maintenance branch is copied to another branch | |
268 | named with the previous release version number (e.g. maint-X.Y.(Z-1) | |
269 | where X.Y.Z is the current release). | |
270 | ||
271 | .Copy maint | |
272 | [caption="Recipe: "] | |
273 | ===================================== | |
274 | `git branch maint-X.Y.(Z-1) maint` | |
275 | ===================================== | |
276 | ||
277 | The 'maint' branch should now be fast-forwarded to the newly released | |
278 | code so that maintenance fixes can be tracked for the current release: | |
279 | ||
280 | .Update maint to new release | |
281 | [caption="Recipe: "] | |
282 | ===================================== | |
283 | * `git checkout maint` | |
284 | * `git merge --ff-only master` | |
285 | ===================================== | |
286 | ||
287 | If the merge fails because it is not a fast-forward, then it is | |
288 | possible some fixes on 'maint' were missed in the feature release. | |
289 | This will not happen if the content of the branches was verified as | |
290 | described in the previous section. | |
291 | ||
292 | ||
293 | Branch management for next and pu after a feature release | |
294 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
295 | ||
296 | After a feature release, the integration branch 'next' may optionally be | |
297 | rewound and rebuilt from the tip of 'master' using the surviving | |
298 | topics on 'next': | |
299 | ||
300 | .Rewind and rebuild next | |
301 | [caption="Recipe: "] | |
302 | ===================================== | |
303 | * `git checkout next` | |
304 | * `git reset --hard master` | |
305 | * `git merge ai/topic_in_next1` | |
306 | * `git merge ai/topic_in_next2` | |
307 | * ... | |
308 | ===================================== | |
309 | ||
310 | The advantage of doing this is that the history of 'next' will be | |
311 | clean. For example, some topics merged into 'next' may have initially | |
312 | looked promising, but were later found to be undesirable or premature. | |
313 | In such a case, the topic is reverted out of 'next' but the fact | |
314 | remains in the history that it was once merged and reverted. By | |
315 | recreating 'next', you give another incarnation of such topics a clean | |
316 | slate to retry, and a feature release is a good point in history to do | |
317 | so. | |
318 | ||
319 | If you do this, then you should make a public announcement indicating | |
320 | that 'next' was rewound and rebuilt. | |
321 | ||
322 | The same rewind and rebuild process may be followed for 'pu'. A public | |
323 | announcement is not necessary since 'pu' is a throw-away branch, as | |
324 | described above. | |
325 | ||
326 | ||
f948dd89 TR |
327 | DISTRIBUTED WORKFLOWS |
328 | --------------------- | |
329 | ||
330 | After the last section, you should know how to manage topics. In | |
331 | general, you will not be the only person working on the project, so | |
332 | you will have to share your work. | |
333 | ||
334 | Roughly speaking, there are two important workflows: merge and patch. | |
335 | The important difference is that the merge workflow can propagate full | |
336 | history, including merges, while patches cannot. Both workflows can | |
337 | be used in parallel: in `git.git`, only subsystem maintainers use | |
338 | the merge workflow, while everyone else sends patches. | |
339 | ||
340 | Note that the maintainer(s) may impose restrictions, such as | |
341 | "Signed-off-by" requirements, that all commits/patches submitted for | |
342 | inclusion must adhere to. Consult your project's documentation for | |
343 | more information. | |
344 | ||
345 | ||
346 | Merge workflow | |
347 | ~~~~~~~~~~~~~~ | |
348 | ||
349 | The merge workflow works by copying branches between upstream and | |
350 | downstream. Upstream can merge contributions into the official | |
351 | history; downstream base their work on the official history. | |
352 | ||
353 | There are three main tools that can be used for this: | |
354 | ||
355 | * linkgit:git-push[1] copies your branches to a remote repository, | |
356 | usually to one that can be read by all involved parties; | |
357 | ||
358 | * linkgit:git-fetch[1] that copies remote branches to your repository; | |
359 | and | |
360 | ||
361 | * linkgit:git-pull[1] that does fetch and merge in one go. | |
362 | ||
363 | Note the last point. Do 'not' use 'git-pull' unless you actually want | |
364 | to merge the remote branch. | |
365 | ||
366 | Getting changes out is easy: | |
367 | ||
368 | .Push/pull: Publishing branches/topics | |
369 | [caption="Recipe: "] | |
370 | ===================================== | |
371 | `git push <remote> <branch>` and tell everyone where they can fetch | |
372 | from. | |
373 | ===================================== | |
374 | ||
375 | You will still have to tell people by other means, such as mail. (Git | |
f3f0c518 | 376 | provides the linkgit:git-request-pull[1] to send preformatted pull |
f948dd89 TR |
377 | requests to upstream maintainers to simplify this task.) |
378 | ||
379 | If you just want to get the newest copies of the integration branches, | |
380 | staying up to date is easy too: | |
381 | ||
382 | .Push/pull: Staying up to date | |
383 | [caption="Recipe: "] | |
384 | ===================================== | |
385 | Use `git fetch <remote>` or `git remote update` to stay up to date. | |
386 | ===================================== | |
387 | ||
388 | Then simply fork your topic branches from the stable remotes as | |
389 | explained earlier. | |
390 | ||
391 | If you are a maintainer and would like to merge other people's topic | |
392 | branches to the integration branches, they will typically send a | |
393 | request to do so by mail. Such a request looks like | |
394 | ||
395 | ------------------------------------- | |
396 | Please pull from | |
397 | <url> <branch> | |
398 | ------------------------------------- | |
399 | ||
400 | In that case, 'git-pull' can do the fetch and merge in one go, as | |
401 | follows. | |
402 | ||
403 | .Push/pull: Merging remote topics | |
404 | [caption="Recipe: "] | |
405 | ===================================== | |
406 | `git pull <url> <branch>` | |
407 | ===================================== | |
408 | ||
409 | Occasionally, the maintainer may get merge conflicts when he tries to | |
410 | pull changes from downstream. In this case, he can ask downstream to | |
411 | do the merge and resolve the conflicts themselves (perhaps they will | |
412 | know better how to resolve them). It is one of the rare cases where | |
413 | downstream 'should' merge from upstream. | |
414 | ||
415 | ||
416 | Patch workflow | |
417 | ~~~~~~~~~~~~~~ | |
418 | ||
419 | If you are a contributor that sends changes upstream in the form of | |
420 | emails, you should use topic branches as usual (see above). Then use | |
421 | linkgit:git-format-patch[1] to generate the corresponding emails | |
422 | (highly recommended over manually formatting them because it makes the | |
423 | maintainer's life easier). | |
424 | ||
425 | .format-patch/am: Publishing branches/topics | |
426 | [caption="Recipe: "] | |
427 | ===================================== | |
428 | * `git format-patch -M upstream..topic` to turn them into preformatted | |
429 | patch files | |
430 | * `git send-email --to=<recipient> <patches>` | |
431 | ===================================== | |
432 | ||
433 | See the linkgit:git-format-patch[1] and linkgit:git-send-email[1] | |
434 | manpages for further usage notes. | |
435 | ||
436 | If the maintainer tells you that your patch no longer applies to the | |
437 | current upstream, you will have to rebase your topic (you cannot use a | |
438 | merge because you cannot format-patch merges): | |
439 | ||
440 | .format-patch/am: Keeping topics up to date | |
441 | [caption="Recipe: "] | |
442 | ===================================== | |
443 | `git pull --rebase <url> <branch>` | |
444 | ===================================== | |
445 | ||
446 | You can then fix the conflicts during the rebase. Presumably you have | |
447 | not published your topic other than by mail, so rebasing it is not a | |
448 | problem. | |
449 | ||
450 | If you receive such a patch series (as maintainer, or perhaps as a | |
451 | reader of the mailing list it was sent to), save the mails to files, | |
452 | create a new topic branch and use 'git-am' to import the commits: | |
453 | ||
454 | .format-patch/am: Importing patches | |
455 | [caption="Recipe: "] | |
456 | ===================================== | |
457 | `git am < patch` | |
458 | ===================================== | |
459 | ||
460 | One feature worth pointing out is the three-way merge, which can help | |
461 | if you get conflicts: `git am -3` will use index information contained | |
462 | in patches to figure out the merge base. See linkgit:git-am[1] for | |
463 | other options. | |
464 | ||
465 | ||
466 | SEE ALSO | |
467 | -------- | |
468 | linkgit:gittutorial[7], | |
469 | linkgit:git-push[1], | |
470 | linkgit:git-pull[1], | |
471 | linkgit:git-merge[1], | |
472 | linkgit:git-rebase[1], | |
473 | linkgit:git-format-patch[1], | |
474 | linkgit:git-send-email[1], | |
475 | linkgit:git-am[1] | |
476 | ||
477 | GIT | |
478 | --- | |
479 | Part of the linkgit:git[1] suite. |