1gitworkflows(7) 2=============== 3 4NAME 5---- 6gitworkflows - An overview of recommended workflows with git 7 8SYNOPSIS 9-------- 10git * 11 12 13DESCRIPTION 14----------- 15 16This document attempts to write down and motivate some of the workflow 17elements used for `git.git` itself. Many ideas apply in general, 18though the full workflow is rarely required for smaller projects with 19fewer people involved. 20 21We formulate a set of 'rules' for quick reference, while the prose 22tries to motivate each of them. Do not always take them literally; 23you should value good reasons for your actions higher than manpages 24such as this one. 25 26 27SEPARATE CHANGES 28---------------- 29 30As a general rule, you should try to split your changes into small 31logical steps, and commit each of them. They should be consistent, 32working independently of any later commits, pass the test suite, etc. 33This makes the review process much easier, and the history much more 34useful for later inspection and analysis, for example with 35linkgit:git-blame[1] and linkgit:git-bisect[1]. 36 37To achieve this, try to split your work into small steps from the very 38beginning. It is always easier to squash a few commits together than 39to split one big commit into several. Don't be afraid of making too 40small or imperfect steps along the way. You can always go back later 41and edit the commits with `git rebase \--interactive` before you 42publish them. You can use `git stash save \--keep-index` to run the 43test suite independent of other uncommitted changes; see the EXAMPLES 44section of linkgit:git-stash[1]. 45 46 47MANAGING BRANCHES 48----------------- 49 50There are two main tools that can be used to include changes from one 51branch on another: linkgit:git-merge[1] and 52linkgit:git-cherry-pick[1]. 53 54Merges have many advantages, so we try to solve as many problems as 55possible with merges alone. Cherry-picking is still occasionally 56useful; see "Merging upwards" below for an example. 57 58Most importantly, merging works at the branch level, while 59cherry-picking works at the commit level. This means that a merge can 60carry over the changes from 1, 10, or 1000 commits with equal ease, 61which in turn means the workflow scales much better to a large number 62of contributors (and contributions). Merges are also easier to 63understand because a merge commit is a "promise" that all changes from 64all its parents are now included. 65 66There is a tradeoff of course: merges require a more careful branch 67management. The following subsections discuss the important points. 68 69 70Graduation 71~~~~~~~~~~ 72 73As 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 85There 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 91Each of the four branches is usually a direct descendant of the one 92above it. 93 94Conceptually, the feature enters at an unstable branch (usually 'next' 95or 'pu'), and "graduates" to 'master' for the next release once it is 96considered stable enough. 97 98 99Merging upwards 100~~~~~~~~~~~~~~~ 101 102The "downwards graduation" discussed above cannot be done by actually 103merging downwards, however, since that would merge 'all' changes on 104the unstable branch into the stable one. Hence the following: 105 106.Merge upwards 107[caption="Rule: "] 108===================================== 109Always commit your fixes to the oldest supported branch that require 110them. Then (periodically) merge the integration branches upwards into each 111other. 112===================================== 113 114This gives a very controlled flow of fixes. If you notice that you 115have applied a fix to e.g. 'master' that is also required in 'maint', 116you will need to cherry-pick it (using linkgit:git-cherry-pick[1]) 117downwards. This will happen a few times and is nothing to worry about 118unless you do it very frequently. 119 120 121Topic branches 122~~~~~~~~~~~~~~ 123 124Any nontrivial feature will require several patches to implement, and 125may get extra bugfixes or improvements during its lifetime. 126 127Committing everything directly on the integration branches leads to many 128problems: Bad commits cannot be undone, so they must be reverted one 129by one, which creates confusing histories and further error potential 130when you forget to revert part of a group of changes. Working in 131parallel mixes up the changes, creating further confusion. 132 133Use of "topic branches" solves these problems. The name is pretty 134self explanatory, with a caveat that comes from the "merge upwards" 135rule above: 136 137.Topic branches 138[caption="Rule: "] 139===================================== 140Make a side branch for every topic (feature, bugfix, ...). Fork it off 141at the oldest integration branch that you will eventually want to merge it 142into. 143===================================== 144 145Many 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 161Note that the last point clashes with the other two: a topic that has 162been merged elsewhere should not be rebased. See the section on 163RECOVERING FROM UPSTREAM REBASE in linkgit:git-rebase[1]. 164 165We should point out that "habitually" (regularly for no real reason) 166merging an integration branch into your topics -- and by extension, 167merging 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===================================== 173Do not merge to downstream except with a good reason: upstream API 174changes affect your branch; your branch no longer merges to upstream 175cleanly; etc. 176===================================== 177 178Otherwise, the topic that was merged to suddenly contains more than a 179single (well-separated) change. The many resulting small merges will 180greatly clutter up history. Anyone who later investigates the history 181of a file will have to find out whether that merge affected the topic 182in development. An upstream might even inadvertently be merged into a 183"more stable" branch. And so on. 184 185 186Throw-away integration 187~~~~~~~~~~~~~~~~~~~~~~ 188 189If you followed the last paragraph, you will now have many small topic 190branches, and occasionally wonder how they interact. Perhaps the 191result of merging them does not even work? But on the other hand, we 192want to avoid merging them anywhere "stable" because such merges 193cannot easily be undone. 194 195The solution, of course, is to make a merge that we can undo: merge 196into a throw-away branch. 197 198.Throw-away integration branches 199[caption="Rule: "] 200===================================== 201To test the interaction of several topics, merge them into a 202throw-away branch. You must never base any work on such a branch! 203===================================== 204 205If you make it (very) clear that this branch is going to be deleted 206right after the testing, you can even publish this branch, for example 207to give the testers a chance to work with it, or other developers a 208chance to see if their in-progress work will be compatible. `git.git` 209has such an official throw-away integration branch called 'pu'. 210 211 212DISTRIBUTED WORKFLOWS 213--------------------- 214 215After the last section, you should know how to manage topics. In 216general, you will not be the only person working on the project, so 217you will have to share your work. 218 219Roughly speaking, there are two important workflows: merge and patch. 220The important difference is that the merge workflow can propagate full 221history, including merges, while patches cannot. Both workflows can 222be used in parallel: in `git.git`, only subsystem maintainers use 223the merge workflow, while everyone else sends patches. 224 225Note that the maintainer(s) may impose restrictions, such as 226"Signed-off-by" requirements, that all commits/patches submitted for 227inclusion must adhere to. Consult your project's documentation for 228more information. 229 230 231Merge workflow 232~~~~~~~~~~~~~~ 233 234The merge workflow works by copying branches between upstream and 235downstream. Upstream can merge contributions into the official 236history; downstream base their work on the official history. 237 238There 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 248Note the last point. Do 'not' use 'git-pull' unless you actually want 249to merge the remote branch. 250 251Getting 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 257from. 258===================================== 259 260You will still have to tell people by other means, such as mail. (Git 261provides the linkgit:git-request-pull[1] to send preformatted pull 262requests to upstream maintainers to simplify this task.) 263 264If you just want to get the newest copies of the integration branches, 265staying up to date is easy too: 266 267.Push/pull: Staying up to date 268[caption="Recipe: "] 269===================================== 270Use `git fetch <remote>` or `git remote update` to stay up to date. 271===================================== 272 273Then simply fork your topic branches from the stable remotes as 274explained earlier. 275 276If you are a maintainer and would like to merge other people's topic 277branches to the integration branches, they will typically send a 278request to do so by mail. Such a request looks like 279 280------------------------------------- 281Please pull from 282 <url> <branch> 283------------------------------------- 284 285In that case, 'git-pull' can do the fetch and merge in one go, as 286follows. 287 288.Push/pull: Merging remote topics 289[caption="Recipe: "] 290===================================== 291`git pull <url> <branch>` 292===================================== 293 294Occasionally, the maintainer may get merge conflicts when he tries to 295pull changes from downstream. In this case, he can ask downstream to 296do the merge and resolve the conflicts themselves (perhaps they will 297know better how to resolve them). It is one of the rare cases where 298downstream 'should' merge from upstream. 299 300 301Patch workflow 302~~~~~~~~~~~~~~ 303 304If you are a contributor that sends changes upstream in the form of 305emails, you should use topic branches as usual (see above). Then use 306linkgit:git-format-patch[1] to generate the corresponding emails 307(highly recommended over manually formatting them because it makes the 308maintainer'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 318See the linkgit:git-format-patch[1] and linkgit:git-send-email[1] 319manpages for further usage notes. 320 321If the maintainer tells you that your patch no longer applies to the 322current upstream, you will have to rebase your topic (you cannot use a 323merge 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 331You can then fix the conflicts during the rebase. Presumably you have 332not published your topic other than by mail, so rebasing it is not a 333problem. 334 335If you receive such a patch series (as maintainer, or perhaps as a 336reader of the mailing list it was sent to), save the mails to files, 337create 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 345One feature worth pointing out is the three-way merge, which can help 346if you get conflicts: `git am -3` will use index information contained 347in patches to figure out the merge base. See linkgit:git-am[1] for 348other options. 349 350 351SEE ALSO 352-------- 353linkgit:gittutorial[7], 354linkgit:git-push[1], 355linkgit:git-pull[1], 356linkgit:git-merge[1], 357linkgit:git-rebase[1], 358linkgit:git-format-patch[1], 359linkgit:git-send-email[1], 360linkgit:git-am[1] 361 362GIT 363--- 364Part of the linkgit:git[1] suite.