Documentation / gitworkflows.txton commit conditional markdown preprocessing (c8b1cd9)
   1gitworkflows(7)
   2===============
   3
   4NAME
   5----
   6gitworkflows - An overview of recommended workflows with Git
   7
   8SYNOPSIS
   9--------
  10[verse]
  11git *
  12
  13
  14DESCRIPTION
  15-----------
  16
  17This document attempts to write down and motivate some of the workflow
  18elements used for `git.git` itself.  Many ideas apply in general,
  19though the full workflow is rarely required for smaller projects with
  20fewer people involved.
  21
  22We formulate a set of 'rules' for quick reference, while the prose
  23tries to motivate each of them.  Do not always take them literally;
  24you should value good reasons for your actions higher than manpages
  25such as this one.
  26
  27
  28SEPARATE CHANGES
  29----------------
  30
  31As a general rule, you should try to split your changes into small
  32logical steps, and commit each of them.  They should be consistent,
  33working independently of any later commits, pass the test suite, etc.
  34This makes the review process much easier, and the history much more
  35useful for later inspection and analysis, for example with
  36linkgit:git-blame[1] and linkgit:git-bisect[1].
  37
  38To achieve this, try to split your work into small steps from the very
  39beginning. It is always easier to squash a few commits together than
  40to split one big commit into several.  Don't be afraid of making too
  41small or imperfect steps along the way. You can always go back later
  42and edit the commits with `git rebase --interactive` before you
  43publish them.  You can use `git stash push --keep-index` to run the
  44test suite independent of other uncommitted changes; see the EXAMPLES
  45section of linkgit:git-stash[1].
  46
  47
  48MANAGING BRANCHES
  49-----------------
  50
  51There are two main tools that can be used to include changes from one
  52branch on another: linkgit:git-merge[1] and
  53linkgit:git-cherry-pick[1].
  54
  55Merges have many advantages, so we try to solve as many problems as
  56possible with merges alone.  Cherry-picking is still occasionally
  57useful; see "Merging upwards" below for an example.
  58
  59Most importantly, merging works at the branch level, while
  60cherry-picking works at the commit level.  This means that a merge can
  61carry over the changes from 1, 10, or 1000 commits with equal ease,
  62which in turn means the workflow scales much better to a large number
  63of contributors (and contributions).  Merges are also easier to
  64understand because a merge commit is a "promise" that all changes from
  65all its parents are now included.
  66
  67There is a tradeoff of course: merges require a more careful branch
  68management.  The following subsections discuss the important points.
  69
  70
  71Graduation
  72~~~~~~~~~~
  73
  74As 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
  86There 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
  92Each of the four branches is usually a direct descendant of the one
  93above it.
  94
  95Conceptually, the feature enters at an unstable branch (usually 'next'
  96or 'pu'), and "graduates" to 'master' for the next release once it is
  97considered stable enough.
  98
  99
 100Merging upwards
 101~~~~~~~~~~~~~~~
 102
 103The "downwards graduation" discussed above cannot be done by actually
 104merging downwards, however, since that would merge 'all' changes on
 105the unstable branch into the stable one.  Hence the following:
 106
 107.Merge upwards
 108[caption="Rule: "]
 109=====================================
 110Always commit your fixes to the oldest supported branch that requires
 111them.  Then (periodically) merge the integration branches upwards into each
 112other.
 113=====================================
 114
 115This gives a very controlled flow of fixes.  If you notice that you
 116have applied a fix to e.g. 'master' that is also required in 'maint',
 117you will need to cherry-pick it (using linkgit:git-cherry-pick[1])
 118downwards.  This will happen a few times and is nothing to worry about
 119unless you do it very frequently.
 120
 121
 122Topic branches
 123~~~~~~~~~~~~~~
 124
 125Any nontrivial feature will require several patches to implement, and
 126may get extra bugfixes or improvements during its lifetime.
 127
 128Committing everything directly on the integration branches leads to many
 129problems: Bad commits cannot be undone, so they must be reverted one
 130by one, which creates confusing histories and further error potential
 131when you forget to revert part of a group of changes.  Working in
 132parallel mixes up the changes, creating further confusion.
 133
 134Use of "topic branches" solves these problems.  The name is pretty
 135self explanatory, with a caveat that comes from the "merge upwards"
 136rule above:
 137
 138.Topic branches
 139[caption="Rule: "]
 140=====================================
 141Make a side branch for every topic (feature, bugfix, ...). Fork it off
 142at the oldest integration branch that you will eventually want to merge it
 143into.
 144=====================================
 145
 146Many 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
 162Note that the last point clashes with the other two: a topic that has
 163been merged elsewhere should not be rebased.  See the section on
 164RECOVERING FROM UPSTREAM REBASE in linkgit:git-rebase[1].
 165
 166We should point out that "habitually" (regularly for no real reason)
 167merging an integration branch into your topics -- and by extension,
 168merging 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=====================================
 174Do not merge to downstream except with a good reason: upstream API
 175changes affect your branch; your branch no longer merges to upstream
 176cleanly; etc.
 177=====================================
 178
 179Otherwise, the topic that was merged to suddenly contains more than a
 180single (well-separated) change.  The many resulting small merges will
 181greatly clutter up history.  Anyone who later investigates the history
 182of a file will have to find out whether that merge affected the topic
 183in development.  An upstream might even inadvertently be merged into a
 184"more stable" branch.  And so on.
 185
 186
 187Throw-away integration
 188~~~~~~~~~~~~~~~~~~~~~~
 189
 190If you followed the last paragraph, you will now have many small topic
 191branches, and occasionally wonder how they interact.  Perhaps the
 192result of merging them does not even work?  But on the other hand, we
 193want to avoid merging them anywhere "stable" because such merges
 194cannot easily be undone.
 195
 196The solution, of course, is to make a merge that we can undo: merge
 197into a throw-away branch.
 198
 199.Throw-away integration branches
 200[caption="Rule: "]
 201=====================================
 202To test the interaction of several topics, merge them into a
 203throw-away branch.  You must never base any work on such a branch!
 204=====================================
 205
 206If you make it (very) clear that this branch is going to be deleted
 207right after the testing, you can even publish this branch, for example
 208to give the testers a chance to work with it, or other developers a
 209chance to see if their in-progress work will be compatible.  `git.git`
 210has such an official throw-away integration branch called 'pu'.
 211
 212
 213Branch management for a release
 214~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 215
 216Assuming you are using the merge approach discussed above, when you
 217are releasing your project you will need to do some additional branch
 218management work.
 219
 220A feature release is created from the 'master' branch, since 'master'
 221tracks the commits that should go into the next feature release.
 222
 223The 'master' branch is supposed to be a superset of 'maint'. If this
 224condition does not hold, then 'maint' contains some commits that
 225are not included on 'master'. The fixes represented by those commits
 226will therefore not be included in your feature release.
 227
 228To 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=====================================
 233`git log master..maint`
 234=====================================
 235
 236This command should not list any commits.  Otherwise, check out
 237'master' and merge 'maint' into it.
 238
 239Now you can proceed with the creation of the feature release. Apply a
 240tag to the tip of 'master' indicating the release version:
 241
 242.Release tagging
 243[caption="Recipe: "]
 244=====================================
 245`git tag -s -m "Git X.Y.Z" vX.Y.Z master`
 246=====================================
 247
 248You need to push the new tag to a public Git server (see
 249"DISTRIBUTED WORKFLOWS" below). This makes the tag available to
 250others tracking your project. The push could also trigger a
 251post-update hook to perform release-related items such as building
 252release tarballs and preformatted documentation pages.
 253
 254Similarly, for a maintenance release, 'maint' is tracking the commits
 255to be released. Therefore, in the steps above simply tag and push
 256'maint' rather than 'master'.
 257
 258
 259Maintenance branch management after a feature release
 260~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 261
 262After a feature release, you need to manage your maintenance branches.
 263
 264First, if you wish to continue to release maintenance fixes for the
 265feature release made before the recent one, then you must create
 266another branch to track commits for that previous release.
 267
 268To do this, the current maintenance branch is copied to another branch
 269named with the previous release version number (e.g. maint-X.Y.(Z-1)
 270where 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
 278The 'maint' branch should now be fast-forwarded to the newly released
 279code 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
 288If the merge fails because it is not a fast-forward, then it is
 289possible some fixes on 'maint' were missed in the feature release.
 290This will not happen if the content of the branches was verified as
 291described in the previous section.
 292
 293
 294Branch management for next and pu after a feature release
 295~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 296
 297After a feature release, the integration branch 'next' may optionally be
 298rewound and rebuilt from the tip of 'master' using the surviving
 299topics on 'next':
 300
 301.Rewind and rebuild next
 302[caption="Recipe: "]
 303=====================================
 304* `git switch -C next master`
 305* `git merge ai/topic_in_next1`
 306* `git merge ai/topic_in_next2`
 307* ...
 308=====================================
 309
 310The advantage of doing this is that the history of 'next' will be
 311clean. For example, some topics merged into 'next' may have initially
 312looked promising, but were later found to be undesirable or premature.
 313In such a case, the topic is reverted out of 'next' but the fact
 314remains in the history that it was once merged and reverted. By
 315recreating 'next', you give another incarnation of such topics a clean
 316slate to retry, and a feature release is a good point in history to do
 317so.
 318
 319If you do this, then you should make a public announcement indicating
 320that 'next' was rewound and rebuilt.
 321
 322The same rewind and rebuild process may be followed for 'pu'. A public
 323announcement is not necessary since 'pu' is a throw-away branch, as
 324described above.
 325
 326
 327DISTRIBUTED WORKFLOWS
 328---------------------
 329
 330After the last section, you should know how to manage topics.  In
 331general, you will not be the only person working on the project, so
 332you will have to share your work.
 333
 334Roughly speaking, there are two important workflows: merge and patch.
 335The important difference is that the merge workflow can propagate full
 336history, including merges, while patches cannot.  Both workflows can
 337be used in parallel: in `git.git`, only subsystem maintainers use
 338the merge workflow, while everyone else sends patches.
 339
 340Note that the maintainer(s) may impose restrictions, such as
 341"Signed-off-by" requirements, that all commits/patches submitted for
 342inclusion must adhere to.  Consult your project's documentation for
 343more information.
 344
 345
 346Merge workflow
 347~~~~~~~~~~~~~~
 348
 349The merge workflow works by copying branches between upstream and
 350downstream.  Upstream can merge contributions into the official
 351history; downstream base their work on the official history.
 352
 353There 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
 363Note the last point.  Do 'not' use 'git pull' unless you actually want
 364to merge the remote branch.
 365
 366Getting 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
 372from.
 373=====================================
 374
 375You will still have to tell people by other means, such as mail.  (Git
 376provides the linkgit:git-request-pull[1] to send preformatted pull
 377requests to upstream maintainers to simplify this task.)
 378
 379If you just want to get the newest copies of the integration branches,
 380staying up to date is easy too:
 381
 382.Push/pull: Staying up to date
 383[caption="Recipe: "]
 384=====================================
 385Use `git fetch <remote>` or `git remote update` to stay up to date.
 386=====================================
 387
 388Then simply fork your topic branches from the stable remotes as
 389explained earlier.
 390
 391If you are a maintainer and would like to merge other people's topic
 392branches to the integration branches, they will typically send a
 393request to do so by mail.  Such a request looks like
 394
 395-------------------------------------
 396Please pull from
 397    <url> <branch>
 398-------------------------------------
 399
 400In that case, 'git pull' can do the fetch and merge in one go, as
 401follows.
 402
 403.Push/pull: Merging remote topics
 404[caption="Recipe: "]
 405=====================================
 406`git pull <url> <branch>`
 407=====================================
 408
 409Occasionally, the maintainer may get merge conflicts when they try to
 410pull changes from downstream.  In this case, they can ask downstream to
 411do the merge and resolve the conflicts themselves (perhaps they will
 412know better how to resolve them).  It is one of the rare cases where
 413downstream 'should' merge from upstream.
 414
 415
 416Patch workflow
 417~~~~~~~~~~~~~~
 418
 419If you are a contributor that sends changes upstream in the form of
 420emails, you should use topic branches as usual (see above).  Then use
 421linkgit:git-format-patch[1] to generate the corresponding emails
 422(highly recommended over manually formatting them because it makes the
 423maintainer'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
 433See the linkgit:git-format-patch[1] and linkgit:git-send-email[1]
 434manpages for further usage notes.
 435
 436If the maintainer tells you that your patch no longer applies to the
 437current upstream, you will have to rebase your topic (you cannot use a
 438merge 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
 446You can then fix the conflicts during the rebase.  Presumably you have
 447not published your topic other than by mail, so rebasing it is not a
 448problem.
 449
 450If you receive such a patch series (as maintainer, or perhaps as a
 451reader of the mailing list it was sent to), save the mails to files,
 452create 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
 460One feature worth pointing out is the three-way merge, which can help
 461if you get conflicts: `git am -3` will use index information contained
 462in patches to figure out the merge base.  See linkgit:git-am[1] for
 463other options.
 464
 465
 466SEE ALSO
 467--------
 468linkgit:gittutorial[7],
 469linkgit:git-push[1],
 470linkgit:git-pull[1],
 471linkgit:git-merge[1],
 472linkgit:git-rebase[1],
 473linkgit:git-format-patch[1],
 474linkgit:git-send-email[1],
 475linkgit:git-am[1]
 476
 477GIT
 478---
 479Part of the linkgit:git[1] suite