merge(third_party/git): Merge squashed git subtree at v2.23.0
Merge commit '1b593e1ea4' as 'third_party/git'
This commit is contained in:
Vincent Ambo
commit
7ef0d62730
3629 changed files with 1139935 additions and 0 deletions
372
third_party/git/Documentation/git-merge.txt
vendored
Normal file
372
third_party/git/Documentation/git-merge.txt
vendored
Normal file
|
|
@ -0,0 +1,372 @@
|
|||
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
|
||||
Loading…
Add table
Add a link
Reference in a new issue