diff options
Diffstat (limited to 'third_party/git/Documentation/git-merge.txt')
| -rw-r--r-- | third_party/git/Documentation/git-merge.txt | 372 |
1 files changed, 0 insertions, 372 deletions
diff --git a/third_party/git/Documentation/git-merge.txt b/third_party/git/Documentation/git-merge.txt deleted file mode 100644 index 01fd52dc70..0000000000 --- a/third_party/git/Documentation/git-merge.txt +++ /dev/null @@ -1,372 +0,0 @@ -git-merge(1) -============ - -NAME ----- -git-merge - Join two or more development histories together - - -SYNOPSIS --------- -[verse] -'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] - [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] - [--[no-]allow-unrelated-histories] - [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [<commit>...] -'git merge' (--continue | --abort | --quit) - -DESCRIPTION ------------ -Incorporates changes from the named commits (since the time their -histories diverged from the current branch) into the current -branch. This command is used by 'git pull' to incorporate changes -from another repository and can be used by hand to merge changes -from one branch into another. - -Assume the following history exists and the current branch is -"`master`": - ------------- - A---B---C topic - / - D---E---F---G master ------------- - -Then "`git merge topic`" will replay the changes made on the -`topic` branch since it diverged from `master` (i.e., `E`) until -its current commit (`C`) on top of `master`, and record the result -in a new commit along with the names of the two parent commits and -a log message from the user describing the changes. - ------------- - A---B---C topic - / \ - D---E---F---G---H master ------------- - -The second syntax ("`git merge --abort`") can only be run after the -merge has resulted in conflicts. 'git merge --abort' will abort the -merge process and try to reconstruct the pre-merge state. However, -if there were uncommitted changes when the merge started (and -especially if those changes were further modified after the merge -was started), 'git merge --abort' will in some cases be unable to -reconstruct the original (pre-merge) changes. Therefore: - -*Warning*: Running 'git merge' with non-trivial uncommitted changes is -discouraged: while possible, it may leave you in a state that is hard to -back out of in the case of a conflict. - -The third syntax ("`git merge --continue`") can only be run after the -merge has resulted in conflicts. - -OPTIONS -------- -include::merge-options.txt[] - --m <msg>:: - Set the commit message to be used for the merge commit (in - case one is created). -+ -If `--log` is specified, a shortlog of the commits being merged -will be appended to the specified message. -+ -The 'git fmt-merge-msg' command can be -used to give a good default for automated 'git merge' -invocations. The automated message can include the branch description. - --F <file>:: ---file=<file>:: - Read the commit message to be used for the merge commit (in - case one is created). -+ -If `--log` is specified, a shortlog of the commits being merged -will be appended to the specified message. - ---rerere-autoupdate:: ---no-rerere-autoupdate:: - Allow the rerere mechanism to update the index with the - result of auto-conflict resolution if possible. - ---overwrite-ignore:: ---no-overwrite-ignore:: - Silently overwrite ignored files from the merge result. This - is the default behavior. Use `--no-overwrite-ignore` to abort. - ---abort:: - Abort the current conflict resolution process, and - try to reconstruct the pre-merge state. -+ -If there were uncommitted worktree changes present when the merge -started, 'git merge --abort' will in some cases be unable to -reconstruct these changes. It is therefore recommended to always -commit or stash your changes before running 'git merge'. -+ -'git merge --abort' is equivalent to 'git reset --merge' when -`MERGE_HEAD` is present. - ---quit:: - Forget about the current merge in progress. Leave the index - and the working tree as-is. - ---continue:: - After a 'git merge' stops due to conflicts you can conclude the - merge by running 'git merge --continue' (see "HOW TO RESOLVE - CONFLICTS" section below). - -<commit>...:: - Commits, usually other branch heads, to merge into our branch. - Specifying more than one commit will create a merge with - more than two parents (affectionately called an Octopus merge). -+ -If no commit is given from the command line, merge the remote-tracking -branches that the current branch is configured to use as its upstream. -See also the configuration section of this manual page. -+ -When `FETCH_HEAD` (and no other commit) is specified, the branches -recorded in the `.git/FETCH_HEAD` file by the previous invocation -of `git fetch` for merging are merged to the current branch. - - -PRE-MERGE CHECKS ----------------- - -Before applying outside changes, you should get your own work in -good shape and committed locally, so it will not be clobbered if -there are conflicts. See also linkgit:git-stash[1]. -'git pull' and 'git merge' will stop without doing anything when -local uncommitted changes overlap with files that 'git pull'/'git -merge' may need to update. - -To avoid recording unrelated changes in the merge commit, -'git pull' and 'git merge' will also abort if there are any changes -registered in the index relative to the `HEAD` commit. (Special -narrow exceptions to this rule may exist depending on which merge -strategy is in use, but generally, the index must match HEAD.) - -If all named commits are already ancestors of `HEAD`, 'git merge' -will exit early with the message "Already up to date." - -FAST-FORWARD MERGE ------------------- - -Often the current branch head is an ancestor of the named commit. -This is the most common case especially when invoked from 'git -pull': you are tracking an upstream repository, you have committed -no local changes, and now you want to update to a newer upstream -revision. In this case, a new commit is not needed to store the -combined history; instead, the `HEAD` (along with the index) is -updated to point at the named commit, without creating an extra -merge commit. - -This behavior can be suppressed with the `--no-ff` option. - -TRUE MERGE ----------- - -Except in a fast-forward merge (see above), the branches to be -merged must be tied together by a merge commit that has both of them -as its parents. - -A merged version reconciling the changes from all branches to be -merged is committed, and your `HEAD`, index, and working tree are -updated to it. It is possible to have modifications in the working -tree as long as they do not overlap; the update will preserve them. - -When it is not obvious how to reconcile the changes, the following -happens: - -1. The `HEAD` pointer stays the same. -2. The `MERGE_HEAD` ref is set to point to the other branch head. -3. Paths that merged cleanly are updated both in the index file and - in your working tree. -4. For conflicting paths, the index file records up to three - versions: stage 1 stores the version from the common ancestor, - stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you - can inspect the stages with `git ls-files -u`). The working - tree files contain the result of the "merge" program; i.e. 3-way - merge results with familiar conflict markers `<<<` `===` `>>>`. -5. No other changes are made. In particular, the local - modifications you had before you started merge will stay the - same and the index entries for them stay as they were, - i.e. matching `HEAD`. - -If you tried a merge which resulted in complex conflicts and -want to start over, you can recover with `git merge --abort`. - -MERGING TAG ------------ - -When merging an annotated (and possibly signed) tag, Git always -creates a merge commit even if a fast-forward merge is possible, and -the commit message template is prepared with the tag message. -Additionally, if the tag is signed, the signature check is reported -as a comment in the message template. See also linkgit:git-tag[1]. - -When you want to just integrate with the work leading to the commit -that happens to be tagged, e.g. synchronizing with an upstream -release point, you may not want to make an unnecessary merge commit. - -In such a case, you can "unwrap" the tag yourself before feeding it -to `git merge`, or pass `--ff-only` when you do not have any work on -your own. e.g. - ----- -git fetch origin -git merge v1.2.3^0 -git merge --ff-only v1.2.3 ----- - - -HOW CONFLICTS ARE PRESENTED ---------------------------- - -During a merge, the working tree files are updated to reflect the result -of the merge. Among the changes made to the common ancestor's version, -non-overlapping ones (that is, you changed an area of the file while the -other side left that area intact, or vice versa) are incorporated in the -final result verbatim. When both sides made changes to the same area, -however, Git cannot randomly pick one side over the other, and asks you to -resolve it by leaving what both sides did to that area. - -By default, Git uses the same style as the one used by the "merge" program -from the RCS suite to present such a conflicted hunk, like this: - ------------- -Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed. -<<<<<<< yours:sample.txt -Conflict resolution is hard; -let's go shopping. -======= -Git makes conflict resolution easy. ->>>>>>> theirs:sample.txt -And here is another line that is cleanly resolved or unmodified. ------------- - -The area where a pair of conflicting changes happened is marked with markers -`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======` -is typically your side, and the part afterwards is typically their side. - -The default format does not show what the original said in the conflicting -area. You cannot tell how many lines are deleted and replaced with -Barbie's remark on your side. The only thing you can tell is that your -side wants to say it is hard and you'd prefer to go shopping, while the -other side wants to claim it is easy. - -An alternative style can be used by setting the "merge.conflictStyle" -configuration variable to "diff3". In "diff3" style, the above conflict -may look like this: - ------------- -Here are lines that are either unchanged from the common -ancestor, or cleanly resolved because only one side changed. -<<<<<<< yours:sample.txt -Conflict resolution is hard; -let's go shopping. -||||||| -Conflict resolution is hard. -======= -Git makes conflict resolution easy. ->>>>>>> theirs:sample.txt -And here is another line that is cleanly resolved or unmodified. ------------- - -In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses -another `|||||||` marker that is followed by the original text. You can -tell that the original just stated a fact, and your side simply gave in to -that statement and gave up, while the other side tried to have a more -positive attitude. You can sometimes come up with a better resolution by -viewing the original. - - -HOW TO RESOLVE CONFLICTS ------------------------- - -After seeing a conflict, you can do two things: - - * Decide not to merge. The only clean-ups you need are to reset - the index file to the `HEAD` commit to reverse 2. and to clean - up working tree changes made by 2. and 3.; `git merge --abort` - can be used for this. - - * Resolve the conflicts. Git will mark the conflicts in - the working tree. Edit the files into shape and - 'git add' them to the index. Use 'git commit' or - 'git merge --continue' to seal the deal. The latter command - checks whether there is a (interrupted) merge in progress - before calling 'git commit'. - -You can work through the conflict with a number of tools: - - * Use a mergetool. `git mergetool` to launch a graphical - mergetool which will work you through the merge. - - * Look at the diffs. `git diff` will show a three-way diff, - highlighting changes from both the `HEAD` and `MERGE_HEAD` - versions. - - * Look at the diffs from each branch. `git log --merge -p <path>` - will show diffs first for the `HEAD` version and then the - `MERGE_HEAD` version. - - * Look at the originals. `git show :1:filename` shows the - common ancestor, `git show :2:filename` shows the `HEAD` - version, and `git show :3:filename` shows the `MERGE_HEAD` - version. - - -EXAMPLES --------- - -* Merge branches `fixes` and `enhancements` on top of - the current branch, making an octopus merge: -+ ------------------------------------------------- -$ git merge fixes enhancements ------------------------------------------------- - -* Merge branch `obsolete` into the current branch, using `ours` - merge strategy: -+ ------------------------------------------------- -$ git merge -s ours obsolete ------------------------------------------------- - -* Merge branch `maint` into the current branch, but do not make - a new commit automatically: -+ ------------------------------------------------- -$ git merge --no-commit maint ------------------------------------------------- -+ -This can be used when you want to include further changes to the -merge, or want to write your own merge commit message. -+ -You should refrain from abusing this option to sneak substantial -changes into a merge commit. Small fixups like bumping -release/version name would be acceptable. - - -include::merge-strategies.txt[] - -CONFIGURATION -------------- -include::config/merge.txt[] - -branch.<name>.mergeOptions:: - Sets default options for merging into branch <name>. The syntax and - supported options are the same as those of 'git merge', but option - values containing whitespace characters are currently not supported. - -SEE ALSO --------- -linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], -linkgit:gitattributes[5], -linkgit:git-reset[1], -linkgit:git-diff[1], linkgit:git-ls-files[1], -linkgit:git-add[1], linkgit:git-rm[1], -linkgit:git-mergetool[1] - -GIT ---- -Part of the linkgit:git[1] suite |