diff options
Diffstat (limited to 'third_party/git/Documentation/gitworkflows.txt')
| -rw-r--r-- | third_party/git/Documentation/gitworkflows.txt | 479 |
1 files changed, 0 insertions, 479 deletions
diff --git a/third_party/git/Documentation/gitworkflows.txt b/third_party/git/Documentation/gitworkflows.txt deleted file mode 100644 index 47cf97f9bea2..000000000000 --- a/third_party/git/Documentation/gitworkflows.txt +++ /dev/null @@ -1,479 +0,0 @@ -gitworkflows(7) -=============== - -NAME ----- -gitworkflows - An overview of recommended workflows with Git - -SYNOPSIS --------- -[verse] -git * - - -DESCRIPTION ------------ - -This document attempts to write down and motivate some of the workflow -elements used for `git.git` itself. Many ideas apply in general, -though the full workflow is rarely required for smaller projects with -fewer people involved. - -We formulate a set of 'rules' for quick reference, while the prose -tries to motivate each of them. Do not always take them literally; -you should value good reasons for your actions higher than manpages -such as this one. - - -SEPARATE CHANGES ----------------- - -As a general rule, you should try to split your changes into small -logical steps, and commit each of them. They should be consistent, -working independently of any later commits, pass the test suite, etc. -This makes the review process much easier, and the history much more -useful for later inspection and analysis, for example with -linkgit:git-blame[1] and linkgit:git-bisect[1]. - -To achieve this, try to split your work into small steps from the very -beginning. It is always easier to squash a few commits together than -to split one big commit into several. Don't be afraid of making too -small or imperfect steps along the way. You can always go back later -and edit the commits with `git rebase --interactive` before you -publish them. You can use `git stash push --keep-index` to run the -test suite independent of other uncommitted changes; see the EXAMPLES -section of linkgit:git-stash[1]. - - -MANAGING BRANCHES ------------------ - -There are two main tools that can be used to include changes from one -branch on another: linkgit:git-merge[1] and -linkgit:git-cherry-pick[1]. - -Merges have many advantages, so we try to solve as many problems as -possible with merges alone. Cherry-picking is still occasionally -useful; see "Merging upwards" below for an example. - -Most importantly, merging works at the branch level, while -cherry-picking works at the commit level. This means that a merge can -carry over the changes from 1, 10, or 1000 commits with equal ease, -which in turn means the workflow scales much better to a large number -of contributors (and contributions). Merges are also easier to -understand because a merge commit is a "promise" that all changes from -all its parents are now included. - -There is a tradeoff of course: merges require a more careful branch -management. The following subsections discuss the important points. - - -Graduation -~~~~~~~~~~ - -As a given feature goes from experimental to stable, it also -"graduates" between the corresponding branches of the software. -`git.git` uses the following 'integration branches': - -* 'maint' tracks the commits that should go into the next "maintenance - release", i.e., update of the last released stable version; - -* 'master' tracks the commits that should go into the next release; - -* 'next' is intended as a testing branch for topics being tested for - stability for master. - -There is a fourth official branch that is used slightly differently: - -* 'seen' (patches seen by the maintainer) is an integration branch for - things that are not quite ready for inclusion yet (see "Integration - Branches" below). - -Each of the four branches is usually a direct descendant of the one -above it. - -Conceptually, the feature enters at an unstable branch (usually 'next' -or 'seen'), and "graduates" to 'master' for the next release once it is -considered stable enough. - - -Merging upwards -~~~~~~~~~~~~~~~ - -The "downwards graduation" discussed above cannot be done by actually -merging downwards, however, since that would merge 'all' changes on -the unstable branch into the stable one. Hence the following: - -.Merge upwards -[caption="Rule: "] -===================================== -Always commit your fixes to the oldest supported branch that requires -them. Then (periodically) merge the integration branches upwards into each -other. -===================================== - -This gives a very controlled flow of fixes. If you notice that you -have applied a fix to e.g. 'master' that is also required in 'maint', -you will need to cherry-pick it (using linkgit:git-cherry-pick[1]) -downwards. This will happen a few times and is nothing to worry about -unless you do it very frequently. - - -Topic branches -~~~~~~~~~~~~~~ - -Any nontrivial feature will require several patches to implement, and -may get extra bugfixes or improvements during its lifetime. - -Committing everything directly on the integration branches leads to many -problems: Bad commits cannot be undone, so they must be reverted one -by one, which creates confusing histories and further error potential -when you forget to revert part of a group of changes. Working in -parallel mixes up the changes, creating further confusion. - -Use of "topic branches" solves these problems. The name is pretty -self explanatory, with a caveat that comes from the "merge upwards" -rule above: - -.Topic branches -[caption="Rule: "] -===================================== -Make a side branch for every topic (feature, bugfix, ...). Fork it off -at the oldest integration branch that you will eventually want to merge it -into. -===================================== - -Many things can then be done very naturally: - -* To get the feature/bugfix into an integration branch, simply merge - it. If the topic has evolved further in the meantime, merge again. - (Note that you do not necessarily have to merge it to the oldest - integration branch first. For example, you can first merge a bugfix - to 'next', give it some testing time, and merge to 'maint' when you - know it is stable.) - -* If you find you need new features from the branch 'other' to continue - working on your topic, merge 'other' to 'topic'. (However, do not - do this "just habitually", see below.) - -* If you find you forked off the wrong branch and want to move it - "back in time", use linkgit:git-rebase[1]. - -Note that the last point clashes with the other two: a topic that has -been merged elsewhere should not be rebased. See the section on -RECOVERING FROM UPSTREAM REBASE in linkgit:git-rebase[1]. - -We should point out that "habitually" (regularly for no real reason) -merging an integration branch into your topics -- and by extension, -merging anything upstream into anything downstream on a regular basis --- is frowned upon: - -.Merge to downstream only at well-defined points -[caption="Rule: "] -===================================== -Do not merge to downstream except with a good reason: upstream API -changes affect your branch; your branch no longer merges to upstream -cleanly; etc. -===================================== - -Otherwise, the topic that was merged to suddenly contains more than a -single (well-separated) change. The many resulting small merges will -greatly clutter up history. Anyone who later investigates the history -of a file will have to find out whether that merge affected the topic -in development. An upstream might even inadvertently be merged into a -"more stable" branch. And so on. - - -Throw-away integration -~~~~~~~~~~~~~~~~~~~~~~ - -If you followed the last paragraph, you will now have many small topic -branches, and occasionally wonder how they interact. Perhaps the -result of merging them does not even work? But on the other hand, we -want to avoid merging them anywhere "stable" because such merges -cannot easily be undone. - -The solution, of course, is to make a merge that we can undo: merge -into a throw-away branch. - -.Throw-away integration branches -[caption="Rule: "] -===================================== -To test the interaction of several topics, merge them into a -throw-away branch. You must never base any work on such a branch! -===================================== - -If you make it (very) clear that this branch is going to be deleted -right after the testing, you can even publish this branch, for example -to give the testers a chance to work with it, or other developers a -chance to see if their in-progress work will be compatible. `git.git` -has such an official throw-away integration branch called 'seen'. - - -Branch management for a release -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Assuming you are using the merge approach discussed above, when you -are releasing your project you will need to do some additional branch -management work. - -A feature release is created from the 'master' branch, since 'master' -tracks the commits that should go into the next feature release. - -The 'master' branch is supposed to be a superset of 'maint'. If this -condition does not hold, then 'maint' contains some commits that -are not included on 'master'. The fixes represented by those commits -will therefore not be included in your feature release. - -To verify that 'master' is indeed a superset of 'maint', use git log: - -.Verify 'master' is a superset of 'maint' -[caption="Recipe: "] -===================================== -`git log master..maint` -===================================== - -This command should not list any commits. Otherwise, check out -'master' and merge 'maint' into it. - -Now you can proceed with the creation of the feature release. Apply a -tag to the tip of 'master' indicating the release version: - -.Release tagging -[caption="Recipe: "] -===================================== -`git tag -s -m "Git X.Y.Z" vX.Y.Z master` -===================================== - -You need to push the new tag to a public Git server (see -"DISTRIBUTED WORKFLOWS" below). This makes the tag available to -others tracking your project. The push could also trigger a -post-update hook to perform release-related items such as building -release tarballs and preformatted documentation pages. - -Similarly, for a maintenance release, 'maint' is tracking the commits -to be released. Therefore, in the steps above simply tag and push -'maint' rather than 'master'. - - -Maintenance branch management after a feature release -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -After a feature release, you need to manage your maintenance branches. - -First, if you wish to continue to release maintenance fixes for the -feature release made before the recent one, then you must create -another branch to track commits for that previous release. - -To do this, the current maintenance branch is copied to another branch -named with the previous release version number (e.g. maint-X.Y.(Z-1) -where X.Y.Z is the current release). - -.Copy maint -[caption="Recipe: "] -===================================== -`git branch maint-X.Y.(Z-1) maint` -===================================== - -The 'maint' branch should now be fast-forwarded to the newly released -code so that maintenance fixes can be tracked for the current release: - -.Update maint to new release -[caption="Recipe: "] -===================================== -* `git checkout maint` -* `git merge --ff-only master` -===================================== - -If the merge fails because it is not a fast-forward, then it is -possible some fixes on 'maint' were missed in the feature release. -This will not happen if the content of the branches was verified as -described in the previous section. - - -Branch management for next and seen after a feature release -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -After a feature release, the integration branch 'next' may optionally be -rewound and rebuilt from the tip of 'master' using the surviving -topics on 'next': - -.Rewind and rebuild next -[caption="Recipe: "] -===================================== -* `git switch -C next master` -* `git merge ai/topic_in_next1` -* `git merge ai/topic_in_next2` -* ... -===================================== - -The advantage of doing this is that the history of 'next' will be -clean. For example, some topics merged into 'next' may have initially -looked promising, but were later found to be undesirable or premature. -In such a case, the topic is reverted out of 'next' but the fact -remains in the history that it was once merged and reverted. By -recreating 'next', you give another incarnation of such topics a clean -slate to retry, and a feature release is a good point in history to do -so. - -If you do this, then you should make a public announcement indicating -that 'next' was rewound and rebuilt. - -The same rewind and rebuild process may be followed for 'seen'. A public -announcement is not necessary since 'seen' is a throw-away branch, as -described above. - - -DISTRIBUTED WORKFLOWS ---------------------- - -After the last section, you should know how to manage topics. In -general, you will not be the only person working on the project, so -you will have to share your work. - -Roughly speaking, there are two important workflows: merge and patch. -The important difference is that the merge workflow can propagate full -history, including merges, while patches cannot. Both workflows can -be used in parallel: in `git.git`, only subsystem maintainers use -the merge workflow, while everyone else sends patches. - -Note that the maintainer(s) may impose restrictions, such as -"Signed-off-by" requirements, that all commits/patches submitted for -inclusion must adhere to. Consult your project's documentation for -more information. - - -Merge workflow -~~~~~~~~~~~~~~ - -The merge workflow works by copying branches between upstream and -downstream. Upstream can merge contributions into the official -history; downstream base their work on the official history. - -There are three main tools that can be used for this: - -* linkgit:git-push[1] copies your branches to a remote repository, - usually to one that can be read by all involved parties; - -* linkgit:git-fetch[1] that copies remote branches to your repository; - and - -* linkgit:git-pull[1] that does fetch and merge in one go. - -Note the last point. Do 'not' use 'git pull' unless you actually want -to merge the remote branch. - -Getting changes out is easy: - -.Push/pull: Publishing branches/topics -[caption="Recipe: "] -===================================== -`git push <remote> <branch>` and tell everyone where they can fetch -from. -===================================== - -You will still have to tell people by other means, such as mail. (Git -provides the linkgit:git-request-pull[1] to send preformatted pull -requests to upstream maintainers to simplify this task.) - -If you just want to get the newest copies of the integration branches, -staying up to date is easy too: - -.Push/pull: Staying up to date -[caption="Recipe: "] -===================================== -Use `git fetch <remote>` or `git remote update` to stay up to date. -===================================== - -Then simply fork your topic branches from the stable remotes as -explained earlier. - -If you are a maintainer and would like to merge other people's topic -branches to the integration branches, they will typically send a -request to do so by mail. Such a request looks like - -------------------------------------- -Please pull from - <url> <branch> -------------------------------------- - -In that case, 'git pull' can do the fetch and merge in one go, as -follows. - -.Push/pull: Merging remote topics -[caption="Recipe: "] -===================================== -`git pull <url> <branch>` -===================================== - -Occasionally, the maintainer may get merge conflicts when they try to -pull changes from downstream. In this case, they can ask downstream to -do the merge and resolve the conflicts themselves (perhaps they will -know better how to resolve them). It is one of the rare cases where -downstream 'should' merge from upstream. - - -Patch workflow -~~~~~~~~~~~~~~ - -If you are a contributor that sends changes upstream in the form of -emails, you should use topic branches as usual (see above). Then use -linkgit:git-format-patch[1] to generate the corresponding emails -(highly recommended over manually formatting them because it makes the -maintainer's life easier). - -.format-patch/am: Publishing branches/topics -[caption="Recipe: "] -===================================== -* `git format-patch -M upstream..topic` to turn them into preformatted - patch files -* `git send-email --to=<recipient> <patches>` -===================================== - -See the linkgit:git-format-patch[1] and linkgit:git-send-email[1] -manpages for further usage notes. - -If the maintainer tells you that your patch no longer applies to the -current upstream, you will have to rebase your topic (you cannot use a -merge because you cannot format-patch merges): - -.format-patch/am: Keeping topics up to date -[caption="Recipe: "] -===================================== -`git pull --rebase <url> <branch>` -===================================== - -You can then fix the conflicts during the rebase. Presumably you have -not published your topic other than by mail, so rebasing it is not a -problem. - -If you receive such a patch series (as maintainer, or perhaps as a -reader of the mailing list it was sent to), save the mails to files, -create a new topic branch and use 'git am' to import the commits: - -.format-patch/am: Importing patches -[caption="Recipe: "] -===================================== -`git am < patch` -===================================== - -One feature worth pointing out is the three-way merge, which can help -if you get conflicts: `git am -3` will use index information contained -in patches to figure out the merge base. See linkgit:git-am[1] for -other options. - - -SEE ALSO --------- -linkgit:gittutorial[7], -linkgit:git-push[1], -linkgit:git-pull[1], -linkgit:git-merge[1], -linkgit:git-rebase[1], -linkgit:git-format-patch[1], -linkgit:git-send-email[1], -linkgit:git-am[1] - -GIT ---- -Part of the linkgit:git[1] suite |