]>
Commit | Line | Data |
---|---|---|
f948dd89 TR |
1 | gitworkflows(7) |
2 | =============== | |
3 | ||
4 | NAME | |
5 | ---- | |
2de9b711 | 6 | gitworkflows - An overview of recommended workflows with Git |
f948dd89 TR |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
7791a1d9 | 10 | [verse] |
f948dd89 TR |
11 | git * |
12 | ||
13 | ||
14 | DESCRIPTION | |
15 | ----------- | |
16 | ||
17 | This document attempts to write down and motivate some of the workflow | |
18 | elements used for `git.git` itself. Many ideas apply in general, | |
19 | though the full workflow is rarely required for smaller projects with | |
20 | fewer people involved. | |
21 | ||
22 | We formulate a set of 'rules' for quick reference, while the prose | |
23 | tries to motivate each of them. Do not always take them literally; | |
24 | you should value good reasons for your actions higher than manpages | |
25 | such as this one. | |
26 | ||
27 | ||
28 | SEPARATE CHANGES | |
29 | ---------------- | |
30 | ||
31 | As a general rule, you should try to split your changes into small | |
32 | logical steps, and commit each of them. They should be consistent, | |
33 | working independently of any later commits, pass the test suite, etc. | |
34 | This makes the review process much easier, and the history much more | |
35 | useful for later inspection and analysis, for example with | |
36 | linkgit:git-blame[1] and linkgit:git-bisect[1]. | |
37 | ||
38 | To achieve this, try to split your work into small steps from the very | |
39 | beginning. It is always easier to squash a few commits together than | |
40 | to split one big commit into several. Don't be afraid of making too | |
41 | small or imperfect steps along the way. You can always go back later | |
6cf378f0 | 42 | and edit the commits with `git rebase --interactive` before you |
db37745e | 43 | publish them. You can use `git stash push --keep-index` to run the |
f948dd89 TR |
44 | test suite independent of other uncommitted changes; see the EXAMPLES |
45 | section of linkgit:git-stash[1]. | |
46 | ||
47 | ||
48 | MANAGING BRANCHES | |
49 | ----------------- | |
50 | ||
51 | There are two main tools that can be used to include changes from one | |
52 | branch on another: linkgit:git-merge[1] and | |
53 | linkgit:git-cherry-pick[1]. | |
54 | ||
55 | Merges have many advantages, so we try to solve as many problems as | |
56 | possible with merges alone. Cherry-picking is still occasionally | |
57 | useful; see "Merging upwards" below for an example. | |
58 | ||
59 | Most importantly, merging works at the branch level, while | |
60 | cherry-picking works at the commit level. This means that a merge can | |
61 | carry over the changes from 1, 10, or 1000 commits with equal ease, | |
62 | which in turn means the workflow scales much better to a large number | |
63 | of contributors (and contributions). Merges are also easier to | |
64 | understand because a merge commit is a "promise" that all changes from | |
65 | all its parents are now included. | |
66 | ||
67 | There is a tradeoff of course: merges require a more careful branch | |
68 | management. The following subsections discuss the important points. | |
69 | ||
70 | ||
71 | Graduation | |
72 | ~~~~~~~~~~ | |
73 | ||
74 | As a given feature goes from experimental to stable, it also | |
75 | "graduates" between the corresponding branches of the software. | |
76 | `git.git` uses the following 'integration branches': | |
77 | ||
78 | * 'maint' tracks the commits that should go into the next "maintenance | |
79 | release", i.e., update of the last released stable version; | |
80 | ||
81 | * 'master' tracks the commits that should go into the next release; | |
82 | ||
83 | * 'next' is intended as a testing branch for topics being tested for | |
84 | stability for master. | |
85 | ||
86 | There is a fourth official branch that is used slightly differently: | |
87 | ||
88 | * 'pu' (proposed updates) is an integration branch for things that are | |
89 | not quite ready for inclusion yet (see "Integration Branches" | |
90 | below). | |
91 | ||
92 | Each of the four branches is usually a direct descendant of the one | |
93 | above it. | |
94 | ||
95 | Conceptually, the feature enters at an unstable branch (usually 'next' | |
96 | or 'pu'), and "graduates" to 'master' for the next release once it is | |
97 | considered stable enough. | |
98 | ||
99 | ||
100 | Merging upwards | |
101 | ~~~~~~~~~~~~~~~ | |
102 | ||
103 | The "downwards graduation" discussed above cannot be done by actually | |
104 | merging downwards, however, since that would merge 'all' changes on | |
105 | the unstable branch into the stable one. Hence the following: | |
106 | ||
107 | .Merge upwards | |
108 | [caption="Rule: "] | |
109 | ===================================== | |
58ebd936 | 110 | Always commit your fixes to the oldest supported branch that requires |
f948dd89 TR |
111 | them. Then (periodically) merge the integration branches upwards into each |
112 | other. | |
113 | ===================================== | |
114 | ||
115 | This gives a very controlled flow of fixes. If you notice that you | |
116 | have applied a fix to e.g. 'master' that is also required in 'maint', | |
117 | you will need to cherry-pick it (using linkgit:git-cherry-pick[1]) | |
118 | downwards. This will happen a few times and is nothing to worry about | |
119 | unless you do it very frequently. | |
120 | ||
121 | ||
122 | Topic branches | |
123 | ~~~~~~~~~~~~~~ | |
124 | ||
125 | Any nontrivial feature will require several patches to implement, and | |
126 | may get extra bugfixes or improvements during its lifetime. | |
127 | ||
128 | Committing everything directly on the integration branches leads to many | |
129 | problems: Bad commits cannot be undone, so they must be reverted one | |
130 | by one, which creates confusing histories and further error potential | |
131 | when you forget to revert part of a group of changes. Working in | |
132 | parallel mixes up the changes, creating further confusion. | |
133 | ||
134 | Use of "topic branches" solves these problems. The name is pretty | |
135 | self explanatory, with a caveat that comes from the "merge upwards" | |
136 | rule above: | |
137 | ||
138 | .Topic branches | |
139 | [caption="Rule: "] | |
140 | ===================================== | |
141 | Make a side branch for every topic (feature, bugfix, ...). Fork it off | |
142 | at the oldest integration branch that you will eventually want to merge it | |
143 | into. | |
144 | ===================================== | |
145 | ||
146 | Many things can then be done very naturally: | |
147 | ||
148 | * To get the feature/bugfix into an integration branch, simply merge | |
149 | it. If the topic has evolved further in the meantime, merge again. | |
150 | (Note that you do not necessarily have to merge it to the oldest | |
151 | integration branch first. For example, you can first merge a bugfix | |
152 | to 'next', give it some testing time, and merge to 'maint' when you | |
153 | know it is stable.) | |
154 | ||
155 | * If you find you need new features from the branch 'other' to continue | |
156 | working on your topic, merge 'other' to 'topic'. (However, do not | |
157 | do this "just habitually", see below.) | |
158 | ||
159 | * If you find you forked off the wrong branch and want to move it | |
160 | "back in time", use linkgit:git-rebase[1]. | |
161 | ||
162 | Note that the last point clashes with the other two: a topic that has | |
163 | been merged elsewhere should not be rebased. See the section on | |
164 | RECOVERING FROM UPSTREAM REBASE in linkgit:git-rebase[1]. | |
165 | ||
166 | We should point out that "habitually" (regularly for no real reason) | |
167 | merging an integration branch into your topics -- and by extension, | |
168 | merging anything upstream into anything downstream on a regular basis | |
169 | -- is frowned upon: | |
170 | ||
171 | .Merge to downstream only at well-defined points | |
172 | [caption="Rule: "] | |
173 | ===================================== | |
174 | Do not merge to downstream except with a good reason: upstream API | |
175 | changes affect your branch; your branch no longer merges to upstream | |
176 | cleanly; etc. | |
177 | ===================================== | |
178 | ||
179 | Otherwise, the topic that was merged to suddenly contains more than a | |
180 | single (well-separated) change. The many resulting small merges will | |
181 | greatly clutter up history. Anyone who later investigates the history | |
182 | of a file will have to find out whether that merge affected the topic | |
183 | in development. An upstream might even inadvertently be merged into a | |
184 | "more stable" branch. And so on. | |
185 | ||
186 | ||
187 | Throw-away integration | |
188 | ~~~~~~~~~~~~~~~~~~~~~~ | |
189 | ||
190 | If you followed the last paragraph, you will now have many small topic | |
191 | branches, and occasionally wonder how they interact. Perhaps the | |
192 | result of merging them does not even work? But on the other hand, we | |
193 | want to avoid merging them anywhere "stable" because such merges | |
194 | cannot easily be undone. | |
195 | ||
196 | The solution, of course, is to make a merge that we can undo: merge | |
197 | into a throw-away branch. | |
198 | ||
199 | .Throw-away integration branches | |
200 | [caption="Rule: "] | |
201 | ===================================== | |
202 | To test the interaction of several topics, merge them into a | |
203 | throw-away branch. You must never base any work on such a branch! | |
204 | ===================================== | |
205 | ||
206 | If you make it (very) clear that this branch is going to be deleted | |
207 | right after the testing, you can even publish this branch, for example | |
208 | to give the testers a chance to work with it, or other developers a | |
209 | chance to see if their in-progress work will be compatible. `git.git` | |
210 | has such an official throw-away integration branch called 'pu'. | |
211 | ||
212 | ||
382e5431 RG |
213 | Branch management for a release |
214 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
215 | ||
216 | Assuming you are using the merge approach discussed above, when you | |
217 | are releasing your project you will need to do some additional branch | |
218 | management work. | |
219 | ||
220 | A feature release is created from the 'master' branch, since 'master' | |
221 | tracks the commits that should go into the next feature release. | |
222 | ||
223 | The 'master' branch is supposed to be a superset of 'maint'. If this | |
224 | condition does not hold, then 'maint' contains some commits that | |
225 | are not included on 'master'. The fixes represented by those commits | |
226 | will therefore not be included in your feature release. | |
227 | ||
228 | To verify that 'master' is indeed a superset of 'maint', use git log: | |
229 | ||
230 | .Verify 'master' is a superset of 'maint' | |
231 | [caption="Recipe: "] | |
232 | ===================================== | |
c8e1c3d3 | 233 | `git log master..maint` |
382e5431 RG |
234 | ===================================== |
235 | ||
236 | This command should not list any commits. Otherwise, check out | |
237 | 'master' and merge 'maint' into it. | |
238 | ||
239 | Now you can proceed with the creation of the feature release. Apply a | |
240 | tag to the tip of 'master' indicating the release version: | |
241 | ||
242 | .Release tagging | |
243 | [caption="Recipe: "] | |
244 | ===================================== | |
48a8c26c | 245 | `git tag -s -m "Git X.Y.Z" vX.Y.Z master` |
382e5431 RG |
246 | ===================================== |
247 | ||
2de9b711 | 248 | You need to push the new tag to a public Git server (see |
382e5431 RG |
249 | "DISTRIBUTED WORKFLOWS" below). This makes the tag available to |
250 | others tracking your project. The push could also trigger a | |
251 | post-update hook to perform release-related items such as building | |
252 | release tarballs and preformatted documentation pages. | |
253 | ||
254 | Similarly, for a maintenance release, 'maint' is tracking the commits | |
255 | to be released. Therefore, in the steps above simply tag and push | |
256 | 'maint' rather than 'master'. | |
257 | ||
258 | ||
259 | Maintenance branch management after a feature release | |
260 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
261 | ||
262 | After a feature release, you need to manage your maintenance branches. | |
263 | ||
264 | First, if you wish to continue to release maintenance fixes for the | |
265 | feature release made before the recent one, then you must create | |
266 | another branch to track commits for that previous release. | |
267 | ||
268 | To do this, the current maintenance branch is copied to another branch | |
269 | named with the previous release version number (e.g. maint-X.Y.(Z-1) | |
270 | where X.Y.Z is the current release). | |
271 | ||
272 | .Copy maint | |
273 | [caption="Recipe: "] | |
274 | ===================================== | |
275 | `git branch maint-X.Y.(Z-1) maint` | |
276 | ===================================== | |
277 | ||
278 | The 'maint' branch should now be fast-forwarded to the newly released | |
279 | code so that maintenance fixes can be tracked for the current release: | |
280 | ||
281 | .Update maint to new release | |
282 | [caption="Recipe: "] | |
283 | ===================================== | |
284 | * `git checkout maint` | |
285 | * `git merge --ff-only master` | |
286 | ===================================== | |
287 | ||
288 | If the merge fails because it is not a fast-forward, then it is | |
289 | possible some fixes on 'maint' were missed in the feature release. | |
290 | This will not happen if the content of the branches was verified as | |
291 | described in the previous section. | |
292 | ||
293 | ||
294 | Branch management for next and pu after a feature release | |
295 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
296 | ||
297 | After a feature release, the integration branch 'next' may optionally be | |
298 | rewound and rebuilt from the tip of 'master' using the surviving | |
299 | topics on 'next': | |
300 | ||
301 | .Rewind and rebuild next | |
302 | [caption="Recipe: "] | |
303 | ===================================== | |
328c6cb8 | 304 | * `git switch -C next master` |
382e5431 RG |
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 | ||
0b444cdb | 363 | Note the last point. Do 'not' use 'git pull' unless you actually want |
f948dd89 TR |
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 | ||
0b444cdb | 400 | In that case, 'git pull' can do the fetch and merge in one go, as |
f948dd89 TR |
401 | follows. |
402 | ||
403 | .Push/pull: Merging remote topics | |
404 | [caption="Recipe: "] | |
405 | ===================================== | |
406 | `git pull <url> <branch>` | |
407 | ===================================== | |
408 | ||
6b0eb884 DB |
409 | Occasionally, the maintainer may get merge conflicts when they try to |
410 | pull changes from downstream. In this case, they can ask downstream to | |
f948dd89 TR |
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, | |
0b444cdb | 452 | create a new topic branch and use 'git am' to import the commits: |
f948dd89 TR |
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 | --- | |
941b9c52 | 479 | Part of the linkgit:git[1] suite |