]>
Commit | Line | Data |
---|---|---|
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:git-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. |