1GITWORKFLOWS(7)                   Git Manual                   GITWORKFLOWS(7)
2
3
4

NAME

6       gitworkflows - An overview of recommended workflows with Git
7

SYNOPSIS

9       git *
10

DESCRIPTION

12       This document attempts to write down and motivate some of the workflow
13       elements used for git.git itself. Many ideas apply in general, though
14       the full workflow is rarely required for smaller projects with fewer
15       people involved.
16
17       We formulate a set of rules for quick reference, while the prose tries
18       to motivate each of them. Do not always take them literally; you should
19       value good reasons for your actions higher than manpages such as this
20       one.
21

SEPARATE CHANGES

23       As a general rule, you should try to split your changes into small
24       logical steps, and commit each of them. They should be consistent,
25       working independently of any later commits, pass the test suite, etc.
26       This makes the review process much easier, and the history much more
27       useful for later inspection and analysis, for example with git-blame(1)
28       and git-bisect(1).
29
30       To achieve this, try to split your work into small steps from the very
31       beginning. It is always easier to squash a few commits together than to
32       split one big commit into several. Don’t be afraid of making too small
33       or imperfect steps along the way. You can always go back later and edit
34       the commits with git rebase --interactive before you publish them. You
35       can use git stash push --keep-index to run the test suite independent
36       of other uncommitted changes; see the EXAMPLES section of git-stash(1).
37

MANAGING BRANCHES

39       There are two main tools that can be used to include changes from one
40       branch on another: git-merge(1) and git-cherry-pick(1).
41
42       Merges have many advantages, so we try to solve as many problems as
43       possible with merges alone. Cherry-picking is still occasionally
44       useful; see "Merging upwards" below for an example.
45
46       Most importantly, merging works at the branch level, while
47       cherry-picking works at the commit level. This means that a merge can
48       carry over the changes from 1, 10, or 1000 commits with equal ease,
49       which in turn means the workflow scales much better to a large number
50       of contributors (and contributions). Merges are also easier to
51       understand because a merge commit is a "promise" that all changes from
52       all its parents are now included.
53
54       There is a tradeoff of course: merges require a more careful branch
55       management. The following subsections discuss the important points.
56
57   Graduation
58       As a given feature goes from experimental to stable, it also
59       "graduates" between the corresponding branches of the software. git.git
60       uses the following integration branches:
61
62maint tracks the commits that should go into the next "maintenance
63           release", i.e., update of the last released stable version;
64
65master tracks the commits that should go into the next release;
66
67next is intended as a testing branch for topics being tested for
68           stability for master.
69
70       There is a fourth official branch that is used slightly differently:
71
72seen (patches seen by the maintainer) is an integration branch for
73           things that are not quite ready for inclusion yet (see "Integration
74           Branches" below).
75
76       Each of the four branches is usually a direct descendant of the one
77       above it.
78
79       Conceptually, the feature enters at an unstable branch (usually next or
80       seen), and "graduates" to master for the next release once it is
81       considered stable enough.
82
83   Merging upwards
84       The "downwards graduation" discussed above cannot be done by actually
85       merging downwards, however, since that would merge all changes on the
86       unstable branch into the stable one. Hence the following:
87
88       Example 1. Merge upwards
89
90       Always commit your fixes to the oldest supported branch that requires
91       them. Then (periodically) merge the integration branches upwards into
92       each other.
93
94       This gives a very controlled flow of fixes. If you notice that you have
95       applied a fix to e.g. master that is also required in maint, you will
96       need to cherry-pick it (using git-cherry-pick(1)) downwards. This will
97       happen a few times and is nothing to worry about unless you do it very
98       frequently.
99
100   Topic branches
101       Any nontrivial feature will require several patches to implement, and
102       may get extra bugfixes or improvements during its lifetime.
103
104       Committing everything directly on the integration branches leads to
105       many problems: Bad commits cannot be undone, so they must be reverted
106       one by one, which creates confusing histories and further error
107       potential when you forget to revert part of a group of changes. Working
108       in parallel mixes up the changes, creating further confusion.
109
110       Use of "topic branches" solves these problems. The name is pretty self
111       explanatory, with a caveat that comes from the "merge upwards" rule
112       above:
113
114       Example 2. Topic branches
115
116       Make a side branch for every topic (feature, bugfix, ...). Fork it off
117       at the oldest integration branch that you will eventually want to merge
118       it into.
119
120       Many things can then be done very naturally:
121
122       •   To get the feature/bugfix into an integration branch, simply merge
123           it. If the topic has evolved further in the meantime, merge again.
124           (Note that you do not necessarily have to merge it to the oldest
125           integration branch first. For example, you can first merge a bugfix
126           to next, give it some testing time, and merge to maint when you
127           know it is stable.)
128
129       •   If you find you need new features from the branch other to continue
130           working on your topic, merge other to topic. (However, do not do
131           this "just habitually", see below.)
132
133       •   If you find you forked off the wrong branch and want to move it
134           "back in time", use git-rebase(1).
135
136       Note that the last point clashes with the other two: a topic that has
137       been merged elsewhere should not be rebased. See the section on
138       RECOVERING FROM UPSTREAM REBASE in git-rebase(1).
139
140       We should point out that "habitually" (regularly for no real reason)
141       merging an integration branch into your topics — and by extension,
142       merging anything upstream into anything downstream on a regular basis —
143       is frowned upon:
144
145       Example 3. Merge to downstream only at well-defined points
146
147       Do not merge to downstream except with a good reason: upstream API
148       changes affect your branch; your branch no longer merges to upstream
149       cleanly; etc.
150
151       Otherwise, the topic that was merged to suddenly contains more than a
152       single (well-separated) change. The many resulting small merges will
153       greatly clutter up history. Anyone who later investigates the history
154       of a file will have to find out whether that merge affected the topic
155       in development. An upstream might even inadvertently be merged into a
156       "more stable" branch. And so on.
157
158   Throw-away integration
159       If you followed the last paragraph, you will now have many small topic
160       branches, and occasionally wonder how they interact. Perhaps the result
161       of merging them does not even work? But on the other hand, we want to
162       avoid merging them anywhere "stable" because such merges cannot easily
163       be undone.
164
165       The solution, of course, is to make a merge that we can undo: merge
166       into a throw-away branch.
167
168       Example 4. Throw-away integration branches
169
170       To test the interaction of several topics, merge them into a throw-away
171       branch. You must never base any work on such a branch!
172
173       If you make it (very) clear that this branch is going to be deleted
174       right after the testing, you can even publish this branch, for example
175       to give the testers a chance to work with it, or other developers a
176       chance to see if their in-progress work will be compatible. git.git has
177       such an official throw-away integration branch called seen.
178
179   Branch management for a release
180       Assuming you are using the merge approach discussed above, when you are
181       releasing your project you will need to do some additional branch
182       management work.
183
184       A feature release is created from the master branch, since master
185       tracks the commits that should go into the next feature release.
186
187       The master branch is supposed to be a superset of maint. If this
188       condition does not hold, then maint contains some commits that are not
189       included on master. The fixes represented by those commits will
190       therefore not be included in your feature release.
191
192       To verify that master is indeed a superset of maint, use git log:
193
194       Example 5. Verify master is a superset of maint
195
196       git log master..maint
197
198       This command should not list any commits. Otherwise, check out master
199       and merge maint into it.
200
201       Now you can proceed with the creation of the feature release. Apply a
202       tag to the tip of master indicating the release version:
203
204       Example 6. Release tagging
205
206       git tag -s -m "Git X.Y.Z" vX.Y.Z master
207
208       You need to push the new tag to a public Git server (see "DISTRIBUTED
209       WORKFLOWS" below). This makes the tag available to others tracking your
210       project. The push could also trigger a post-update hook to perform
211       release-related items such as building release tarballs and
212       preformatted documentation pages.
213
214       Similarly, for a maintenance release, maint is tracking the commits to
215       be released. Therefore, in the steps above simply tag and push maint
216       rather than master.
217
218   Maintenance branch management after a feature release
219       After a feature release, you need to manage your maintenance branches.
220
221       First, if you wish to continue to release maintenance fixes for the
222       feature release made before the recent one, then you must create
223       another branch to track commits for that previous release.
224
225       To do this, the current maintenance branch is copied to another branch
226       named with the previous release version number (e.g. maint-X.Y.(Z-1)
227       where X.Y.Z is the current release).
228
229       Example 7. Copy maint
230
231       git branch maint-X.Y.(Z-1) maint
232
233       The maint branch should now be fast-forwarded to the newly released
234       code so that maintenance fixes can be tracked for the current release:
235
236       Example 8. Update maint to new release
237
238git checkout maint
239
240git merge --ff-only master
241
242       If the merge fails because it is not a fast-forward, then it is
243       possible some fixes on maint were missed in the feature release. This
244       will not happen if the content of the branches was verified as
245       described in the previous section.
246
247   Branch management for next and seen after a feature release
248       After a feature release, the integration branch next may optionally be
249       rewound and rebuilt from the tip of master using the surviving topics
250       on next:
251
252       Example 9. Rewind and rebuild next
253
254git switch -C next master
255
256git merge ai/topic_in_next1
257
258git merge ai/topic_in_next2
259
260       •   ...
261
262       The advantage of doing this is that the history of next will be clean.
263       For example, some topics merged into next may have initially looked
264       promising, but were later found to be undesirable or premature. In such
265       a case, the topic is reverted out of next but the fact remains in the
266       history that it was once merged and reverted. By recreating next, you
267       give another incarnation of such topics a clean slate to retry, and a
268       feature release is a good point in history to do so.
269
270       If you do this, then you should make a public announcement indicating
271       that next was rewound and rebuilt.
272
273       The same rewind and rebuild process may be followed for seen. A public
274       announcement is not necessary since seen is a throw-away branch, as
275       described above.
276

DISTRIBUTED WORKFLOWS

278       After the last section, you should know how to manage topics. In
279       general, you will not be the only person working on the project, so you
280       will have to share your work.
281
282       Roughly speaking, there are two important workflows: merge and patch.
283       The important difference is that the merge workflow can propagate full
284       history, including merges, while patches cannot. Both workflows can be
285       used in parallel: in git.git, only subsystem maintainers use the merge
286       workflow, while everyone else sends patches.
287
288       Note that the maintainer(s) may impose restrictions, such as
289       "Signed-off-by" requirements, that all commits/patches submitted for
290       inclusion must adhere to. Consult your project’s documentation for more
291       information.
292
293   Merge workflow
294       The merge workflow works by copying branches between upstream and
295       downstream. Upstream can merge contributions into the official history;
296       downstream base their work on the official history.
297
298       There are three main tools that can be used for this:
299
300git-push(1) copies your branches to a remote repository, usually to
301           one that can be read by all involved parties;
302
303git-fetch(1) that copies remote branches to your repository; and
304
305git-pull(1) that does fetch and merge in one go.
306
307       Note the last point. Do not use git pull unless you actually want to
308       merge the remote branch.
309
310       Getting changes out is easy:
311
312       Example 10. Push/pull: Publishing branches/topics
313
314       git push <remote> <branch> and tell everyone where they can fetch from.
315
316       You will still have to tell people by other means, such as mail. (Git
317       provides the git-request-pull(1) to send preformatted pull requests to
318       upstream maintainers to simplify this task.)
319
320       If you just want to get the newest copies of the integration branches,
321       staying up to date is easy too:
322
323       Example 11. Push/pull: Staying up to date
324
325       Use git fetch <remote> or git remote update to stay up to date.
326
327       Then simply fork your topic branches from the stable remotes as
328       explained earlier.
329
330       If you are a maintainer and would like to merge other people’s topic
331       branches to the integration branches, they will typically send a
332       request to do so by mail. Such a request looks like
333
334           Please pull from
335               <URL> <branch>
336
337       In that case, git pull can do the fetch and merge in one go, as
338       follows.
339
340       Example 12. Push/pull: Merging remote topics
341
342       git pull <URL> <branch>
343
344       Occasionally, the maintainer may get merge conflicts when they try to
345       pull changes from downstream. In this case, they can ask downstream to
346       do the merge and resolve the conflicts themselves (perhaps they will
347       know better how to resolve them). It is one of the rare cases where
348       downstream should merge from upstream.
349
350   Patch workflow
351       If you are a contributor that sends changes upstream in the form of
352       emails, you should use topic branches as usual (see above). Then use
353       git-format-patch(1) to generate the corresponding emails (highly
354       recommended over manually formatting them because it makes the
355       maintainer’s life easier).
356
357       Example 13. format-patch/am: Publishing branches/topics
358
359git format-patch -M upstream..topic to turn them into preformatted
360           patch files
361
362git send-email --to=<recipient> <patches>
363
364       See the git-format-patch(1) and git-send-email(1) manpages for further
365       usage notes.
366
367       If the maintainer tells you that your patch no longer applies to the
368       current upstream, you will have to rebase your topic (you cannot use a
369       merge because you cannot format-patch merges):
370
371       Example 14. format-patch/am: Keeping topics up to date
372
373       git pull --rebase <URL> <branch>
374
375       You can then fix the conflicts during the rebase. Presumably you have
376       not published your topic other than by mail, so rebasing it is not a
377       problem.
378
379       If you receive such a patch series (as maintainer, or perhaps as a
380       reader of the mailing list it was sent to), save the mails to files,
381       create a new topic branch and use git am to import the commits:
382
383       Example 15. format-patch/am: Importing patches
384
385       git am < patch
386
387       One feature worth pointing out is the three-way merge, which can help
388       if you get conflicts: git am -3 will use index information contained in
389       patches to figure out the merge base. See git-am(1) for other options.
390

SEE ALSO

392       gittutorial(7), git-push(1), git-pull(1), git-merge(1), git-rebase(1),
393       git-format-patch(1), git-send-email(1), git-am(1)
394

GIT

396       Part of the git(1) suite
397
398
399
400Git 2.43.0                        11/20/2023                   GITWORKFLOWS(7)
Impressum