admin/git
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'ja/doc-synopsis-style'

Browse Source 
Doc mark-up fixes.

* ja/doc-synopsis-style:
  doc: convert git-switch manpage to new synopsis style
  doc: convert git-mergetool options to new synopsis style
  doc: convert git-mergetool manpage to new synopsis style
  doc: switch merge config description to new synopsis format
  doc: convert merge strategies to synopsis format
  doc: merge-options.adoc remove a misleading double negation
  doc: convert merge options to new synopsis format
  doc: convert git-merge manpage to new style
  doc: convert git-checkout manpage to new style
This commit is contained in:
Junio C Hamano
2025-06-02 09:25:33 -07:00
parent 7014b55638 b983aaabc8
commit 4f91e606fb
12 changed files with 401 additions and 398 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
Documentation/config/checkout.adoc
View File

@@ -1,9 +1,9 @@
checkout.defaultRemote:: `checkout.defaultRemote`::
When you run `git checkout <something>` When you run `git checkout <something>`
or `git switch <something>` and only have one or `git switch <something>` and only have one
remote, it may implicitly fall back on checking out and remote, it may implicitly fall back on checking out and
tracking e.g. `origin/<something>`. This stops working as soon tracking e.g. `origin/<something>`. This stops working as soon
as you have more than one remote with a `<something>` as you have more than one remote with a _<something>_
reference. This setting allows for setting the name of a reference. This setting allows for setting the name of a
preferred remote that should always win when it comes to preferred remote that should always win when it comes to
disambiguation. The typical use-case is to set this to disambiguation. The typical use-case is to set this to
@@ -12,17 +12,17 @@ checkout.defaultRemote::
Currently this is used by linkgit:git-switch[1] and Currently this is used by linkgit:git-switch[1] and
linkgit:git-checkout[1] when `git checkout <something>` linkgit:git-checkout[1] when `git checkout <something>`
or `git switch <something>` or `git switch <something>`
will checkout the `<something>` branch on another remote, will checkout the _<something>_ branch on another remote,
and by linkgit:git-worktree[1] when `git worktree add` refers to a and by linkgit:git-worktree[1] when `git worktree add` refers to a
remote branch. This setting might be used for other checkout-like remote branch. This setting might be used for other checkout-like
commands or functionality in the future. commands or functionality in the future.
checkout.guess:: `checkout.guess`::
Provides the default value for the `--guess` or `--no-guess` Provides the default value for the `--guess` or `--no-guess`
option in `git checkout` and `git switch`. See option in `git checkout` and `git switch`. See
linkgit:git-switch[1] and linkgit:git-checkout[1]. linkgit:git-switch[1] and linkgit:git-checkout[1].
checkout.workers:: `checkout.workers`::
The number of parallel workers to use when updating the working tree. The number of parallel workers to use when updating the working tree.
The default is one, i.e. sequential execution. If set to a value less The default is one, i.e. sequential execution. If set to a value less
than one, Git will use as many workers as the number of logical cores than one, Git will use as many workers as the number of logical cores
@@ -30,13 +30,13 @@ checkout.workers::
all commands that perform checkout. E.g. checkout, clone, reset, all commands that perform checkout. E.g. checkout, clone, reset,
sparse-checkout, etc. sparse-checkout, etc.
+ +
Note: Parallel checkout usually delivers better performance for repositories NOTE: Parallel checkout usually delivers better performance for repositories
located on SSDs or over NFS. For repositories on spinning disks and/or machines located on SSDs or over NFS. For repositories on spinning disks and/or machines
with a small number of cores, the default sequential checkout often performs with a small number of cores, the default sequential checkout often performs
better. The size and compression level of a repository might also influence how better. The size and compression level of a repository might also influence how
well the parallel version performs. well the parallel version performs.
checkout.thresholdForParallelism:: `checkout.thresholdForParallelism`::
When running parallel checkout with a small number of files, the cost When running parallel checkout with a small number of files, the cost
of subprocess spawning and inter-process communication might outweigh of subprocess spawning and inter-process communication might outweigh
the parallelization gains. This setting allows you to define the minimum the parallelization gains. This setting allows you to define the minimum

8
Documentation/config/fmt-merge-msg.adoc
View File

@@ -1,19 +1,19 @@
merge.branchdesc:: `merge.branchdesc`::
In addition to branch names, populate the log message with In addition to branch names, populate the log message with
the branch description text associated with them. Defaults the branch description text associated with them. Defaults
to false. to false.
merge.log:: `merge.log`::
In addition to branch names, populate the log message with at In addition to branch names, populate the log message with at
most the specified number of one-line descriptions from the most the specified number of one-line descriptions from the
actual commits that are being merged. Defaults to false, and actual commits that are being merged. Defaults to false, and
true is a synonym for 20. true is a synonym for 20.
merge.suppressDest:: `merge.suppressDest`::
By adding a glob that matches the names of integration By adding a glob that matches the names of integration
branches to this multi-valued configuration variable, the branches to this multi-valued configuration variable, the
default merge message computed for merges into these default merge message computed for merges into these
integration branches will omit "into <branch name>" from integration branches will omit "into _<branch-name>_" from
its title. its title.
+ +
An element with an empty value can be used to clear the list An element with an empty value can be used to clear the list

82
Documentation/config/merge.adoc
View File

@@ -1,9 +1,9 @@
merge.conflictStyle:: `merge.conflictStyle`::
Specify the style in which conflicted hunks are written out to Specify the style in which conflicted hunks are written out to
working tree files upon merge. The default is "merge", which working tree files upon merge. The default is "merge", which
shows a `<<<<<<<` conflict marker, changes made by one side, shows a +<<<<<<<+ conflict marker, changes made by one side,
a `=======` marker, changes made by the other side, and then a `=======` marker, changes made by the other side, and then
a `>>>>>>>` marker. An alternate style, "diff3", adds a `|||||||` a +>>>>>>>+ marker. An alternate style, "diff3", adds a +|||||||+
marker and the original text before the `=======` marker. The marker and the original text before the `=======` marker. The
"merge" style tends to produce smaller conflict regions than diff3, "merge" style tends to produce smaller conflict regions than diff3,
both because of the exclusion of the original text, and because both because of the exclusion of the original text, and because
@@ -13,17 +13,17 @@ merge.conflictStyle::
the conflict region when those matching lines appear near either the conflict region when those matching lines appear near either
the beginning or end of a conflict region. the beginning or end of a conflict region.
merge.defaultToUpstream:: `merge.defaultToUpstream`::
If merge is called without any commit argument, merge the upstream If merge is called without any commit argument, merge the upstream
branches configured for the current branch by using their last branches configured for the current branch by using their last
observed values stored in their remote-tracking branches. observed values stored in their remote-tracking branches.
The values of the `branch.<current branch>.merge` that name the The values of the `branch.<current branch>.merge` that name the
branches at the remote named by `branch.<current branch>.remote` branches at the remote named by `branch.<current-branch>.remote`
are consulted, and then they are mapped via `remote.<remote>.fetch` are consulted, and then they are mapped via `remote.<remote>.fetch`
to their corresponding remote-tracking branches, and the tips of to their corresponding remote-tracking branches, and the tips of
these tracking branches are merged. Defaults to true. these tracking branches are merged. Defaults to true.
merge.ff:: `merge.ff`::
By default, Git does not create an extra merge commit when merging By default, Git does not create an extra merge commit when merging
a commit that is a descendant of the current commit. Instead, the a commit that is a descendant of the current commit. Instead, the
tip of the current branch is fast-forwarded. When set to `false`, tip of the current branch is fast-forwarded. When set to `false`,
@@ -33,42 +33,46 @@ merge.ff::
allowed (equivalent to giving the `--ff-only` option from the allowed (equivalent to giving the `--ff-only` option from the
command line). command line).
merge.verifySignatures:: `merge.verifySignatures`::
If true, this is equivalent to the --verify-signatures command If true, this is equivalent to the `--verify-signatures` command
line option. See linkgit:git-merge[1] for details. line option. See linkgit:git-merge[1] for details.
include::fmt-merge-msg.adoc[] include::fmt-merge-msg.adoc[]
merge.renameLimit:: `merge.renameLimit`::
The number of files to consider in the exhaustive portion of The number of files to consider in the exhaustive portion of
rename detection during a merge. If not specified, defaults rename detection during a merge. If not specified, defaults
to the value of diff.renameLimit. If neither to the value of `diff.renameLimit`. If neither
merge.renameLimit nor diff.renameLimit are specified, `merge.renameLimit` nor `diff.renameLimit` are specified,
currently defaults to 7000. This setting has no effect if currently defaults to 7000. This setting has no effect if
rename detection is turned off. rename detection is turned off.
merge.renames:: `merge.renames`::
Whether Git detects renames. If set to "false", rename detection Whether Git detects renames. If set to `false`, rename detection
is disabled. If set to "true", basic rename detection is enabled. is disabled. If set to `true`, basic rename detection is enabled.
Defaults to the value of diff.renames. Defaults to the value of diff.renames.
merge.directoryRenames:: `merge.directoryRenames`::
Whether Git detects directory renames, affecting what happens at Whether Git detects directory renames, affecting what happens at
merge time to new files added to a directory on one side of merge time to new files added to a directory on one side of
history when that directory was renamed on the other side of history when that directory was renamed on the other side of
history. If merge.directoryRenames is set to "false", directory history. Possible values are:
rename detection is disabled, meaning that such new files will be +
left behind in the old directory. If set to "true", directory --
rename detection is enabled, meaning that such new files will be `false`;; Directory rename detection is disabled, meaning that such new files will be
moved into the new directory. If set to "conflict", a conflict left behind in the old directory.
will be reported for such paths. If merge.renames is false, `true`;; Directory rename detection is enabled, meaning that such new files will be
merge.directoryRenames is ignored and treated as false. Defaults moved into the new directory.
to "conflict". `conflict`;; A conflict will be reported for such paths.
--
+
If `merge.renames` is `false`, `merge.directoryRenames` is ignored and treated
as `false`. Defaults to `conflict`.
merge.renormalize:: `merge.renormalize`::
Tell Git that canonical representation of files in the Tell Git that canonical representation of files in the
repository has changed over time (e.g. earlier commits record repository has changed over time (e.g. earlier commits record
text files with CRLF line endings, but recent ones use LF line text files with _CRLF_ line endings, but recent ones use _LF_ line
endings). In such a repository, for each file where a endings). In such a repository, for each file where a
three-way content merge is needed, Git can convert the data three-way content merge is needed, Git can convert the data
recorded in commits to a canonical form before performing a recorded in commits to a canonical form before performing a
@@ -76,35 +80,35 @@ merge.renormalize::
see section "Merging branches with differing checkin/checkout see section "Merging branches with differing checkin/checkout
attributes" in linkgit:gitattributes[5]. attributes" in linkgit:gitattributes[5].
merge.stat:: `merge.stat`::
Whether to print the diffstat between ORIG_HEAD and the merge result Whether to print the diffstat between `ORIG_HEAD` and the merge result
at the end of the merge. True by default. at the end of the merge. True by default.
merge.autoStash:: `merge.autoStash`::
When set to true, automatically create a temporary stash entry When set to `true`, automatically create a temporary stash entry
before the operation begins, and apply it after the operation before the operation begins, and apply it after the operation
ends. This means that you can run merge on a dirty worktree. ends. This means that you can run merge on a dirty worktree.
However, use with care: the final stash application after a However, use with care: the final stash application after a
successful merge might result in non-trivial conflicts. successful merge might result in non-trivial conflicts.
This option can be overridden by the `--no-autostash` and This option can be overridden by the `--no-autostash` and
`--autostash` options of linkgit:git-merge[1]. `--autostash` options of linkgit:git-merge[1].
Defaults to false. Defaults to `false`.
merge.tool:: `merge.tool`::
Controls which merge tool is used by linkgit:git-mergetool[1]. Controls which merge tool is used by linkgit:git-mergetool[1].
The list below shows the valid built-in values. The list below shows the valid built-in values.
Any other value is treated as a custom merge tool and requires Any other value is treated as a custom merge tool and requires
that a corresponding mergetool.<tool>.cmd variable is defined. that a corresponding `mergetool.<tool>.cmd` variable is defined.
merge.guitool:: `merge.guitool`::
Controls which merge tool is used by linkgit:git-mergetool[1] when the Controls which merge tool is used by linkgit:git-mergetool[1] when the
-g/--gui flag is specified. The list below shows the valid built-in values. `-g`/`--gui` flag is specified. The list below shows the valid built-in values.
Any other value is treated as a custom merge tool and requires that a Any other value is treated as a custom merge tool and requires that a
corresponding mergetool.<guitool>.cmd variable is defined. corresponding `mergetool.<guitool>.cmd` variable is defined.
include::{build_dir}/mergetools-merge.adoc[] include::{build_dir}/mergetools-merge.adoc[]
merge.verbosity:: `merge.verbosity`::
Controls the amount of output shown by the recursive merge Controls the amount of output shown by the recursive merge
strategy. Level 0 outputs nothing except a final error strategy. Level 0 outputs nothing except a final error
message if conflicts were detected. Level 1 outputs only message if conflicts were detected. Level 1 outputs only
@@ -112,15 +116,15 @@ merge.verbosity::
above outputs debugging information. The default is level 2. above outputs debugging information. The default is level 2.
Can be overridden by the `GIT_MERGE_VERBOSITY` environment variable. Can be overridden by the `GIT_MERGE_VERBOSITY` environment variable.
merge.<driver>.name:: `merge.<driver>.name`::
Defines a human-readable name for a custom low-level Defines a human-readable name for a custom low-level
merge driver. See linkgit:gitattributes[5] for details. merge driver. See linkgit:gitattributes[5] for details.
merge.<driver>.driver:: `merge.<driver>.driver`::
Defines the command that implements a custom low-level Defines the command that implements a custom low-level
merge driver. See linkgit:gitattributes[5] for details. merge driver. See linkgit:gitattributes[5] for details.
merge.<driver>.recursive:: `merge.<driver>.recursive`::
Names a low-level merge driver to be used when Names a low-level merge driver to be used when
performing an internal merge between common ancestors. performing an internal merge between common ancestors.
See linkgit:gitattributes[5] for details. See linkgit:gitattributes[5] for details.

54
Documentation/config/mergetool.adoc
View File

@@ -1,24 +1,24 @@
mergetool.<tool>.path:: `mergetool.<tool>.path`::
Override the path for the given tool. This is useful in case Override the path for the given tool. This is useful in case
your tool is not in the PATH. your tool is not in the `$PATH`.
mergetool.<tool>.cmd:: `mergetool.<tool>.cmd`::
Specify the command to invoke the specified merge tool. The Specify the command to invoke the specified merge tool. The
specified command is evaluated in shell with the following specified command is evaluated in shell with the following
variables available: 'BASE' is the name of a temporary file variables available: `BASE` is the name of a temporary file
containing the common base of the files to be merged, if available; containing the common base of the files to be merged, if available;
'LOCAL' is the name of a temporary file containing the contents of `LOCAL` is the name of a temporary file containing the contents of
the file on the current branch; 'REMOTE' is the name of a temporary the file on the current branch; `REMOTE` is the name of a temporary
file containing the contents of the file from the branch being file containing the contents of the file from the branch being
merged; 'MERGED' contains the name of the file to which the merge merged; `MERGED` contains the name of the file to which the merge
tool should write the results of a successful merge. tool should write the results of a successful merge.
mergetool.<tool>.hideResolved:: `mergetool.<tool>.hideResolved`::
Allows the user to override the global `mergetool.hideResolved` value Allows the user to override the global `mergetool.hideResolved` value
for a specific tool. See `mergetool.hideResolved` for the full for a specific tool. See `mergetool.hideResolved` for the full
description. description.
mergetool.<tool>.trustExitCode:: `mergetool.<tool>.trustExitCode`::
For a custom merge command, specify whether the exit code of For a custom merge command, specify whether the exit code of
the merge command can be used to determine whether the merge was the merge command can be used to determine whether the merge was
successful. If this is not set to true then the merge target file successful. If this is not set to true then the merge target file
@@ -26,7 +26,7 @@ mergetool.<tool>.trustExitCode::
if the file has been updated; otherwise, the user is prompted to if the file has been updated; otherwise, the user is prompted to
indicate the success of the merge. indicate the success of the merge.
mergetool.meld.hasOutput:: `mergetool.meld.hasOutput`::
Older versions of `meld` do not support the `--output` option. Older versions of `meld` do not support the `--output` option.
Git will attempt to detect whether `meld` supports `--output` Git will attempt to detect whether `meld` supports `--output`
by inspecting the output of `meld --help`. Configuring by inspecting the output of `meld --help`. Configuring
@@ -35,7 +35,7 @@ mergetool.meld.hasOutput::
to `true` tells Git to unconditionally use the `--output` option, to `true` tells Git to unconditionally use the `--output` option,
and `false` avoids using `--output`. and `false` avoids using `--output`.
mergetool.meld.useAutoMerge:: `mergetool.meld.useAutoMerge`::
When the `--auto-merge` is given, meld will merge all non-conflicting When the `--auto-merge` is given, meld will merge all non-conflicting
parts automatically, highlight the conflicting parts, and wait for parts automatically, highlight the conflicting parts, and wait for
user decision. Setting `mergetool.meld.useAutoMerge` to `true` tells user decision. Setting `mergetool.meld.useAutoMerge` to `true` tells
@@ -45,15 +45,15 @@ mergetool.meld.useAutoMerge::
value of `false` avoids using `--auto-merge` altogether, and is the value of `false` avoids using `--auto-merge` altogether, and is the
default value. default value.
mergetool.<vimdiff variant>.layout:: `mergetool.<variant>.layout`::
Configure the split window layout for vimdiff's `<variant>`, which is any of `vimdiff`, Configure the split window layout for vimdiff's _<variant>_, which is any of `vimdiff`,
`nvimdiff`, `gvimdiff`. `nvimdiff`, `gvimdiff`.
Upon launching `git mergetool` with `--tool=<variant>` (or without `--tool` Upon launching `git mergetool` with `--tool=<variant>` (or without `--tool`
if `merge.tool` is configured as `<variant>`), Git will consult if `merge.tool` is configured as _<variant>_), Git will consult
`mergetool.<variant>.layout` to determine the tool's layout. If the `mergetool.<variant>.layout` to determine the tool's layout. If the
variant-specific configuration is not available, `vimdiff`'s is used as variant-specific configuration is not available, `vimdiff` ' s is used as
fallback. If that too is not available, a default layout with 4 windows fallback. If that too is not available, a default layout with 4 windows
will be used. To configure the layout, see the `BACKEND SPECIFIC HINTS` will be used. To configure the layout, see the 'BACKEND SPECIFIC HINTS'
ifdef::git-mergetool[] ifdef::git-mergetool[]
section. section.
endif::[] endif::[]
@@ -61,39 +61,39 @@ ifndef::git-mergetool[]
section in linkgit:git-mergetool[1]. section in linkgit:git-mergetool[1].
endif::[] endif::[]
mergetool.hideResolved:: `mergetool.hideResolved`::
During a merge, Git will automatically resolve as many conflicts as During a merge, Git will automatically resolve as many conflicts as
possible and write the 'MERGED' file containing conflict markers around possible and write the `$MERGED` file containing conflict markers around
any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally any conflicts that it cannot resolve; `$LOCAL` and `$REMOTE` normally
represent the versions of the file from before Git's conflict are the versions of the file from before Git`s conflict
resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwritten so resolution. This flag causes `$LOCAL` and `$REMOTE` to be overwritten so
that only the unresolved conflicts are presented to the merge tool. Can that only the unresolved conflicts are presented to the merge tool. Can
be configured per-tool via the `mergetool.<tool>.hideResolved` be configured per-tool via the `mergetool.<tool>.hideResolved`
configuration variable. Defaults to `false`. configuration variable. Defaults to `false`.
mergetool.keepBackup:: `mergetool.keepBackup`::
After performing a merge, the original file with conflict markers After performing a merge, the original file with conflict markers
can be saved as a file with a `.orig` extension. If this variable can be saved as a file with a `.orig` extension. If this variable
is set to `false` then this file is not preserved. Defaults to is set to `false` then this file is not preserved. Defaults to
`true` (i.e. keep the backup files). `true` (i.e. keep the backup files).
mergetool.keepTemporaries:: `mergetool.keepTemporaries`::
When invoking a custom merge tool, Git uses a set of temporary When invoking a custom merge tool, Git uses a set of temporary
files to pass to the tool. If the tool returns an error and this files to pass to the tool. If the tool returns an error and this
variable is set to `true`, then these temporary files will be variable is set to `true`, then these temporary files will be
preserved; otherwise, they will be removed after the tool has preserved; otherwise, they will be removed after the tool has
exited. Defaults to `false`. exited. Defaults to `false`.
mergetool.writeToTemp:: `mergetool.writeToTemp`::
Git writes temporary 'BASE', 'LOCAL', and 'REMOTE' versions of Git writes temporary `BASE`, `LOCAL`, and `REMOTE` versions of
conflicting files in the worktree by default. Git will attempt conflicting files in the worktree by default. Git will attempt
to use a temporary directory for these files when set `true`. to use a temporary directory for these files when set `true`.
Defaults to `false`. Defaults to `false`.
mergetool.prompt:: `mergetool.prompt`::
Prompt before each invocation of the merge resolution program. Prompt before each invocation of the merge resolution program.
mergetool.guiDefault:: `mergetool.guiDefault`::
Set `true` to use the `merge.guitool` by default (equivalent to Set `true` to use the `merge.guitool` by default (equivalent to
specifying the `--gui` argument), or `auto` to select `merge.guitool` specifying the `--gui` argument), or `auto` to select `merge.guitool`
or `merge.tool` depending on the presence of a `DISPLAY` environment or `merge.tool` depending on the presence of a `DISPLAY` environment

228
Documentation/git-checkout.adoc
View File

@@ -7,54 +7,54 @@ git-checkout - Switch branches or restore working tree files
SYNOPSIS SYNOPSIS
-------- --------
[verse] [synopsis]
'git checkout' [-q] [-f] [-m] [<branch>] git checkout [-q] [-f] [-m] [<branch>]
'git checkout' [-q] [-f] [-m] --detach [<branch>] git checkout [-q] [-f] [-m] --detach [<branch>]
'git checkout' [-q] [-f] [-m] [--detach] <commit> git checkout [-q] [-f] [-m] [--detach] <commit>
'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>] git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new-branch>] [<start-point>]
'git checkout' [-f] <tree-ish> [--] <pathspec>... git checkout [-f] <tree-ish> [--] <pathspec>...
'git checkout' [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul] git checkout [-f] <tree-ish> --pathspec-from-file=<file> [--pathspec-file-nul]
'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>... git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <pathspec>...
'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul] git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<file> [--pathspec-file-nul]
'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...] git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]
DESCRIPTION DESCRIPTION
----------- -----------
Updates files in the working tree to match the version in the index Updates files in the working tree to match the version in the index
or the specified tree. If no pathspec was given, 'git checkout' will or the specified tree. If no pathspec was given, `git checkout` will
also update `HEAD` to set the specified branch as the current also update `HEAD` to set the specified branch as the current
branch. branch.
'git checkout' [<branch>]:: `git checkout [<branch>]`::
To prepare for working on `<branch>`, switch to it by updating To prepare for working on _<branch>_, switch to it by updating
the index and the files in the working tree, and by pointing the index and the files in the working tree, and by pointing
`HEAD` at the branch. Local modifications to the files in the `HEAD` at the branch. Local modifications to the files in the
working tree are kept, so that they can be committed to the working tree are kept, so that they can be committed to the
`<branch>`. _<branch>_.
+ +
If `<branch>` is not found but there does exist a tracking branch in If _<branch>_ is not found but there does exist a tracking branch in
exactly one remote (call it `<remote>`) with a matching name and exactly one remote (call it _<remote>_) with a matching name and
`--no-guess` is not specified, treat as equivalent to `--no-guess` is not specified, treat as equivalent to
+ +
------------ ------------
$ git checkout -b <branch> --track <remote>/<branch> $ git checkout -b <branch> --track <remote>/<branch>
------------ ------------
+ +
You could omit `<branch>`, in which case the command degenerates to You could omit _<branch>_, in which case the command degenerates to
"check out the current branch", which is a glorified no-op with "check out the current branch", which is a glorified no-op with
rather expensive side-effects to show only the tracking information, rather expensive side-effects to show only the tracking information,
if it exists, for the current branch. if it exists, for the current branch.
'git checkout' -b|-B <new-branch> [<start-point>]:: `git checkout (-b|-B) <new-branch> [<start-point>]`::
Specifying `-b` causes a new branch to be created as if Specifying `-b` causes a new branch to be created as if
linkgit:git-branch[1] were called and then checked out. In linkgit:git-branch[1] were called and then checked out. In
this case you can use the `--track` or `--no-track` options, this case you can use the `--track` or `--no-track` options,
which will be passed to 'git branch'. As a convenience, which will be passed to `git branch`. As a convenience,
`--track` without `-b` implies branch creation; see the `--track` without `-b` implies branch creation; see the
description of `--track` below. description of `--track` below.
+ +
If `-B` is given, `<new-branch>` is created if it doesn't exist; otherwise, it If `-B` is given, _<new-branch>_ is created if it doesn't exist; otherwise, it
is reset. This is the transactional equivalent of is reset. This is the transactional equivalent of
+ +
------------ ------------
@@ -67,30 +67,30 @@ successful (e.g., when the branch is in use in another worktree, not
just the current branch stays the same, but the branch is not reset to just the current branch stays the same, but the branch is not reset to
the start-point, either). the start-point, either).
'git checkout' --detach [<branch>]:: `git checkout --detach [<branch>]`::
'git checkout' [--detach] <commit>:: `git checkout [--detach] <commit>`::
Prepare to work on top of `<commit>`, by detaching `HEAD` at it Prepare to work on top of _<commit>_, by detaching `HEAD` at it
(see "DETACHED HEAD" section), and updating the index and the (see "DETACHED HEAD" section), and updating the index and the
files in the working tree. Local modifications to the files files in the working tree. Local modifications to the files
in the working tree are kept, so that the resulting working in the working tree are kept, so that the resulting working
tree will be the state recorded in the commit plus the local tree will be the state recorded in the commit plus the local
modifications. modifications.
+ +
When the `<commit>` argument is a branch name, the `--detach` option can When the _<commit>_ argument is a branch name, the `--detach` option can
be used to detach `HEAD` at the tip of the branch (`git checkout be used to detach `HEAD` at the tip of the branch (`git checkout
<branch>` would check out that branch without detaching `HEAD`). <branch>` would check out that branch without detaching `HEAD`).
+ +
Omitting `<branch>` detaches `HEAD` at the tip of the current branch. Omitting _<branch>_ detaches `HEAD` at the tip of the current branch.
'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...:: `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...`::
'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]:: `git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]`::
Overwrite the contents of the files that match the pathspec. Overwrite the contents of the files that match the pathspec.
When the `<tree-ish>` (most often a commit) is not given, When the _<tree-ish>_ (most often a commit) is not given,
overwrite working tree with the contents in the index. overwrite working tree with the contents in the index.
When the `<tree-ish>` is given, overwrite both the index and When the _<tree-ish>_ is given, overwrite both the index and
the working tree with the contents at the `<tree-ish>`. the working tree with the contents at the _<tree-ish>_.
+ +
The index may contain unmerged entries because of a previous failed merge. The index may contain unmerged entries because of a previous failed merge.
By default, if you try to check out such an entry from the index, the By default, if you try to check out such an entry from the index, the
@@ -100,7 +100,7 @@ specific side of the merge can be checked out of the index by
using `--ours` or `--theirs`. With `-m`, changes made to the working tree using `--ours` or `--theirs`. With `-m`, changes made to the working tree
file can be discarded to re-create the original conflicted merge result. file can be discarded to re-create the original conflicted merge result.
'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]:: `git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>...]`::
This is similar to the previous mode, but lets you use the This is similar to the previous mode, but lets you use the
interactive interface to show the "diff" output and choose which interactive interface to show the "diff" output and choose which
hunks to use in the result. See below for the description of hunks to use in the result. See below for the description of
@@ -108,19 +108,19 @@ file can be discarded to re-create the original conflicted merge result.
OPTIONS OPTIONS
------- -------
-q:: `-q`::
--quiet:: `--quiet`::
Quiet, suppress feedback messages. Quiet, suppress feedback messages.
--progress:: `--progress`::
--no-progress:: `--no-progress`::
Progress status is reported on the standard error stream Progress status is reported on the standard error stream
by default when it is attached to a terminal, unless `--quiet` by default when it is attached to a terminal, unless `--quiet`
is specified. This flag enables progress reporting even if not is specified. This flag enables progress reporting even if not
attached to a terminal, regardless of `--quiet`. attached to a terminal, regardless of `--quiet`.
-f:: `-f`::
--force:: `--force`::
When switching branches, proceed even if the index or the When switching branches, proceed even if the index or the
working tree differs from `HEAD`, and even if there are untracked working tree differs from `HEAD`, and even if there are untracked
files in the way. This is used to throw away local changes and files in the way. This is used to throw away local changes and
@@ -129,13 +129,13 @@ OPTIONS
When checking out paths from the index, do not fail upon unmerged When checking out paths from the index, do not fail upon unmerged
entries; instead, unmerged entries are ignored. entries; instead, unmerged entries are ignored.
--ours:: `--ours`::
--theirs:: `--theirs`::
When checking out paths from the index, check out stage #2 When checking out paths from the index, check out stage #2
('ours') or #3 ('theirs') for unmerged paths. (`ours`) or #3 (`theirs`) for unmerged paths.
+ +
Note that during `git rebase` and `git pull --rebase`, 'ours' and Note that during `git rebase` and `git pull --rebase`, `ours` and
'theirs' may appear swapped; `--ours` gives the version from the `theirs` may appear swapped; `--ours` gives the version from the
branch the changes are rebased onto, while `--theirs` gives the branch the changes are rebased onto, while `--theirs` gives the
version from the branch that holds your work that is being rebased. version from the branch that holds your work that is being rebased.
+ +
@@ -149,22 +149,22 @@ as `ours` (i.e. "our shared canonical history"), while what you did
on your side branch as `theirs` (i.e. "one contributor's work on top on your side branch as `theirs` (i.e. "one contributor's work on top
of it"). of it").
-b <new-branch>:: `-b <new-branch>`::
Create a new branch named `<new-branch>`, start it at Create a new branch named _<new-branch>_, start it at
`<start-point>`, and check the resulting branch out; _<start-point>_, and check the resulting branch out;
see linkgit:git-branch[1] for details. see linkgit:git-branch[1] for details.
-B <new-branch>:: `-B <new-branch>`::
Creates the branch `<new-branch>`, start it at `<start-point>`; Creates the branch _<new-branch>_, start it at _<start-point>_;
if it already exists, then reset it to `<start-point>`. And then if it already exists, then reset it to _<start-point>_. And then
check the resulting branch out. This is equivalent to running check the resulting branch out. This is equivalent to running
"git branch" with "-f" followed by "git checkout" of that branch; `git branch` with `-f` followed by `git checkout` of that branch;
see linkgit:git-branch[1] for details. see linkgit:git-branch[1] for details.
-t:: `-t`::
--track[=(direct|inherit)]:: `--track[=(direct|inherit)]`::
When creating a new branch, set up "upstream" configuration. See When creating a new branch, set up "upstream" configuration. See
"--track" in linkgit:git-branch[1] for details. `--track` in linkgit:git-branch[1] for details.
+ +
If no `-b` option is given, the name of the new branch will be If no `-b` option is given, the name of the new branch will be
derived from the remote-tracking branch, by looking at the local part of derived from the remote-tracking branch, by looking at the local part of
@@ -176,14 +176,14 @@ off of `origin/hack` (or `remotes/origin/hack`, or even
guessing results in an empty name, the guessing is aborted. You can guessing results in an empty name, the guessing is aborted. You can
explicitly give a name with `-b` in such a case. explicitly give a name with `-b` in such a case.
--no-track:: `--no-track`::
Do not set up "upstream" configuration, even if the Do not set up "upstream" configuration, even if the
`branch.autoSetupMerge` configuration variable is true. `branch.autoSetupMerge` configuration variable is true.
--guess:: `--guess`::
--no-guess:: `--no-guess`::
If `<branch>` is not found but there does exist a tracking If _<branch>_ is not found but there does exist a tracking
branch in exactly one remote (call it `<remote>`) with a branch in exactly one remote (call it _<remote>_) with a
matching name, treat as equivalent to matching name, treat as equivalent to
+ +
------------ ------------
@@ -192,10 +192,10 @@ $ git checkout -b <branch> --track <remote>/<branch>
+ +
If the branch exists in multiple remotes and one of them is named by If the branch exists in multiple remotes and one of them is named by
the `checkout.defaultRemote` configuration variable, we'll use that the `checkout.defaultRemote` configuration variable, we'll use that
one for the purposes of disambiguation, even if the `<branch>` isn't one for the purposes of disambiguation, even if the _<branch>_ isn't
unique across all remotes. Set it to unique across all remotes. Set it to
e.g. `checkout.defaultRemote=origin` to always checkout remote e.g. `checkout.defaultRemote=origin` to always checkout remote
branches from there if `<branch>` is ambiguous but exists on the branches from there if _<branch>_ is ambiguous but exists on the
'origin' remote. See also `checkout.defaultRemote` in 'origin' remote. See also `checkout.defaultRemote` in
linkgit:git-config[1]. linkgit:git-config[1].
+ +
@@ -204,28 +204,28 @@ linkgit:git-config[1].
The default behavior can be set via the `checkout.guess` configuration The default behavior can be set via the `checkout.guess` configuration
variable. variable.
-l:: `-l`::
Create the new branch's reflog; see linkgit:git-branch[1] for Create the new branch's reflog; see linkgit:git-branch[1] for
details. details.
-d:: `-d`::
--detach:: `--detach`::
Rather than checking out a branch to work on it, check out a Rather than checking out a branch to work on it, check out a
commit for inspection and discardable experiments. commit for inspection and discardable experiments.
This is the default behavior of `git checkout <commit>` when This is the default behavior of `git checkout <commit>` when
`<commit>` is not a branch name. See the "DETACHED HEAD" section _<commit>_ is not a branch name. See the "DETACHED HEAD" section
below for details. below for details.
--orphan <new-branch>:: `--orphan <new-branch>`::
Create a new unborn branch, named `<new-branch>`, started from Create a new unborn branch, named _<new-branch>_, started from
`<start-point>` and switch to it. The first commit made on this _<start-point>_ and switch to it. The first commit made on this
new branch will have no parents and it will be the root of a new new branch will have no parents and it will be the root of a new
history totally disconnected from all the other branches and history totally disconnected from all the other branches and
commits. commits.
+ +
The index and the working tree are adjusted as if you had previously run The index and the working tree are adjusted as if you had previously run
`git checkout <start-point>`. This allows you to start a new history `git checkout <start-point>`. This allows you to start a new history
that records a set of paths similar to `<start-point>` by easily running that records a set of paths similar to _<start-point>_ by easily running
`git commit -a` to make the root commit. `git commit -a` to make the root commit.
+ +
This can be useful when you want to publish the tree from a commit This can be useful when you want to publish the tree from a commit
@@ -235,20 +235,20 @@ whose full history contains proprietary or otherwise encumbered bits of
code. code.
+ +
If you want to start a disconnected history that records a set of paths If you want to start a disconnected history that records a set of paths
that is totally different from the one of `<start-point>`, then you should that is totally different from the one of _<start-point>_, then you should
clear the index and the working tree right after creating the orphan clear the index and the working tree right after creating the orphan
branch by running `git rm -rf .` from the top level of the working tree. branch by running `git rm -rf .` from the top level of the working tree.
Afterwards you will be ready to prepare your new files, repopulating the Afterwards you will be ready to prepare your new files, repopulating the
working tree, by copying them from elsewhere, extracting a tarball, etc. working tree, by copying them from elsewhere, extracting a tarball, etc.
--ignore-skip-worktree-bits:: `--ignore-skip-worktree-bits`::
In sparse checkout mode, `git checkout -- <paths>` would In sparse checkout mode, `git checkout -- <path>...` would
update only entries matched by `<paths>` and sparse patterns update only entries matched by _<paths>_ and sparse patterns
in `$GIT_DIR/info/sparse-checkout`. This option ignores in `$GIT_DIR/info/sparse-checkout`. This option ignores
the sparse patterns and adds back any files in `<paths>`. the sparse patterns and adds back any files in `<path>...`.
-m:: `-m`::
--merge:: `--merge`::
When switching branches, When switching branches,
if you have local modifications to one or more files that if you have local modifications to one or more files that
are different between the current branch and the branch to are different between the current branch and the branch to
@@ -269,40 +269,40 @@ used when checking out paths from a tree-ish.
+ +
When switching branches with `--merge`, staged changes may be lost. When switching branches with `--merge`, staged changes may be lost.
--conflict=<style>:: `--conflict=<style>`::
The same as `--merge` option above, but changes the way the The same as `--merge` option above, but changes the way the
conflicting hunks are presented, overriding the conflicting hunks are presented, overriding the
`merge.conflictStyle` configuration variable. Possible values are `merge.conflictStyle` configuration variable. Possible values are
"merge" (default), "diff3", and "zdiff3". `merge` (default), `diff3`, and `zdiff3`.
-p:: `-p`::
--patch:: `--patch`::
Interactively select hunks in the difference between the Interactively select hunks in the difference between the
`<tree-ish>` (or the index, if unspecified) and the working _<tree-ish>_ (or the index, if unspecified) and the working
tree. The chosen hunks are then applied in reverse to the tree. The chosen hunks are then applied in reverse to the
working tree (and if a `<tree-ish>` was specified, the index). working tree (and if a _<tree-ish>_ was specified, the index).
+ +
This means that you can use `git checkout -p` to selectively discard This means that you can use `git checkout -p` to selectively discard
edits from your current working tree. See the ``Interactive Mode'' edits from your current working tree. See the "Interactive Mode"
section of linkgit:git-add[1] to learn how to operate the `--patch` mode. section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
+ +
Note that this option uses the no overlay mode by default (see also Note that this option uses the no overlay mode by default (see also
`--overlay`), and currently doesn't support overlay mode. `--overlay`), and currently doesn't support overlay mode.
--ignore-other-worktrees:: `--ignore-other-worktrees`::
`git checkout` refuses when the wanted branch is already checked `git checkout` refuses when the wanted branch is already checked
out or otherwise in use by another worktree. This option makes out or otherwise in use by another worktree. This option makes
it check the branch out anyway. In other words, the branch can it check the branch out anyway. In other words, the branch can
be in use by more than one worktree. be in use by more than one worktree.
--overwrite-ignore:: `--overwrite-ignore`::
--no-overwrite-ignore:: `--no-overwrite-ignore`::
Silently overwrite ignored files when switching branches. This Silently overwrite ignored files when switching branches. This
is the default behavior. Use `--no-overwrite-ignore` to abort is the default behavior. Use `--no-overwrite-ignore` to abort
the operation when the new branch contains ignored files. the operation when the new branch contains ignored files.
--recurse-submodules:: `--recurse-submodules`::
--no-recurse-submodules:: `--no-recurse-submodules`::
Using `--recurse-submodules` will update the content of all active Using `--recurse-submodules` will update the content of all active
submodules according to the commit recorded in the superproject. If submodules according to the commit recorded in the superproject. If
local modifications in a submodule would be overwritten the checkout local modifications in a submodule would be overwritten the checkout
@@ -311,25 +311,25 @@ Note that this option uses the no overlay mode by default (see also
Just like linkgit:git-submodule[1], this will detach `HEAD` of the Just like linkgit:git-submodule[1], this will detach `HEAD` of the
submodule. submodule.
--overlay:: `--overlay`::
--no-overlay:: `--no-overlay`::
In the default overlay mode, `git checkout` never In the default overlay mode, `git checkout` never
removes files from the index or the working tree. When removes files from the index or the working tree. When
specifying `--no-overlay`, files that appear in the index and specifying `--no-overlay`, files that appear in the index and
working tree, but not in `<tree-ish>` are removed, to make them working tree, but not in _<tree-ish>_ are removed, to make them
match `<tree-ish>` exactly. match _<tree-ish>_ exactly.
--pathspec-from-file=<file>:: `--pathspec-from-file=<file>`::
Pathspec is passed in `<file>` instead of commandline args. If Pathspec is passed in _<file>_ instead of commandline args. If
`<file>` is exactly `-` then standard input is used. Pathspec _<file>_ is exactly `-` then standard input is used. Pathspec
elements are separated by LF or CR/LF. Pathspec elements can be elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be
quoted as explained for the configuration variable `core.quotePath` quoted as explained for the configuration variable `core.quotePath`
(see linkgit:git-config[1]). See also `--pathspec-file-nul` and (see linkgit:git-config[1]). See also `--pathspec-file-nul` and
global `--literal-pathspecs`. global `--literal-pathspecs`.
--pathspec-file-nul:: `--pathspec-file-nul`::
Only meaningful with `--pathspec-from-file`. Pathspec elements are Only meaningful with `--pathspec-from-file`. Pathspec elements are
separated with NUL character and all other characters are taken separated with _NUL_ character and all other characters are taken
literally (including newlines and quotes). literally (including newlines and quotes).
<branch>:: <branch>::
@@ -343,33 +343,33 @@ You can use the `@{-N}` syntax to refer to the N-th last
branch/commit checked out using "git checkout" operation. You may branch/commit checked out using "git checkout" operation. You may
also specify `-` which is synonymous to `@{-1}`. also specify `-` which is synonymous to `@{-1}`.
+ +
As a special case, you may use `A...B` as a shortcut for the As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the
merge base of `A` and `B` if there is exactly one merge base. You can merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can
leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
<new-branch>:: _<new-branch>_::
Name for the new branch. Name for the new branch.
<start-point>:: _<start-point>_::
The name of a commit at which to start the new branch; see The name of a commit at which to start the new branch; see
linkgit:git-branch[1] for details. Defaults to `HEAD`. linkgit:git-branch[1] for details. Defaults to `HEAD`.
+ +
As a special case, you may use `"A...B"` as a shortcut for the As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the
merge base of `A` and `B` if there is exactly one merge base. You can merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can
leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
<tree-ish>:: _<tree-ish>_::
Tree to checkout from (when paths are given). If not specified, Tree to checkout from (when paths are given). If not specified,
the index will be used. the index will be used.
+ +
As a special case, you may use `"A...B"` as a shortcut for the As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the
merge base of `A` and `B` if there is exactly one merge base. You can merge base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can
leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. leave out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
\--:: `--`::
Do not interpret any more arguments as options. Do not interpret any more arguments as options.
<pathspec>...:: `<pathspec>...`::
Limits the paths affected by the operation. Limits the paths affected by the operation.
+ +
For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
@@ -391,7 +391,7 @@ a---b---c branch 'master' (refers to commit 'c')
------------ ------------
When a commit is created in this state, the branch is updated to refer to When a commit is created in this state, the branch is updated to refer to
the new commit. Specifically, 'git commit' creates a new commit `d`, whose the new commit. Specifically, `git commit` creates a new commit `d`, whose
parent is commit `c`, and then updates branch `master` to refer to new parent is commit `c`, and then updates branch `master` to refer to new
commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers
to commit `d`: to commit `d`:
@@ -510,11 +510,11 @@ ARGUMENT DISAMBIGUATION
----------------------- -----------------------
When there is only one argument given and it is not `--` (e.g. `git When there is only one argument given and it is not `--` (e.g. `git
checkout abc`), and when the argument is both a valid `<tree-ish>` checkout abc`), and when the argument is both a valid _<tree-ish>_
(e.g. a branch `abc` exists) and a valid `<pathspec>` (e.g. a file (e.g. a branch `abc` exists) and a valid _<pathspec>_ (e.g. a file
or a directory whose name is "abc" exists), Git would usually ask or a directory whose name is "abc" exists), Git would usually ask
you to disambiguate. Because checking out a branch is so common an you to disambiguate. Because checking out a branch is so common an
operation, however, `git checkout abc` takes "abc" as a `<tree-ish>` operation, however, `git checkout abc` takes "abc" as a _<tree-ish>_
in such a situation. Use `git checkout -- <pathspec>` if you want in such a situation. Use `git checkout -- <pathspec>` if you want
to checkout these paths out of the index. to checkout these paths out of the index.

51
Documentation/git-merge.adoc
View File

@@ -8,13 +8,13 @@ git-merge - Join two or more development histories together
SYNOPSIS SYNOPSIS
-------- --------
[verse] [synopsis]
'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
[--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] [--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
[--[no-]allow-unrelated-histories] [--[no-]allow-unrelated-histories]
[--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>]
[--into-name <branch>] [<commit>...] [--into-name <branch>] [<commit>...]
'git merge' (--continue | --abort | --quit) git merge (--continue | --abort | --quit)
DESCRIPTION DESCRIPTION
----------- -----------
@@ -57,7 +57,7 @@ merge started (and especially if those changes were further modified
after the merge was started), `git merge --abort` will in some cases be after the merge was started), `git merge --abort` will in some cases be
unable to reconstruct the original (pre-merge) changes. Therefore: unable to reconstruct the original (pre-merge) changes. Therefore:
*Warning*: Running `git merge` with non-trivial uncommitted changes is WARNING: Running `git merge` with non-trivial uncommitted changes is
discouraged: while possible, it may leave you in a state that is hard to discouraged: while possible, it may leave you in a state that is hard to
back out of in the case of a conflict. back out of in the case of a conflict.
@@ -67,7 +67,7 @@ OPTIONS
include::merge-options.adoc[] include::merge-options.adoc[]
-m <msg>:: `-m <msg>`::
Set the commit message to be used for the merge commit (in Set the commit message to be used for the merge commit (in
case one is created). case one is created).
+ +
@@ -78,13 +78,13 @@ The `git fmt-merge-msg` command can be
used to give a good default for automated `git merge` used to give a good default for automated `git merge`
invocations. The automated message can include the branch description. invocations. The automated message can include the branch description.
--into-name <branch>:: `--into-name <branch>`::
Prepare the default merge message as if merging to the branch Prepare the default merge message as if merging to the branch
`<branch>`, instead of the name of the real branch to which _<branch>_, instead of the name of the real branch to which
the merge is made. the merge is made.
-F <file>:: `-F <file>`::
--file=<file>:: `--file=<file>`::
Read the commit message to be used for the merge commit (in Read the commit message to be used for the merge commit (in
case one is created). case one is created).
+ +
@@ -93,12 +93,12 @@ will be appended to the specified message.
include::rerere-options.adoc[] include::rerere-options.adoc[]
--overwrite-ignore:: `--overwrite-ignore`::
--no-overwrite-ignore:: `--no-overwrite-ignore`::
Silently overwrite ignored files from the merge result. This Silently overwrite ignored files from the merge result. This
is the default behavior. Use `--no-overwrite-ignore` to abort. is the default behavior. Use `--no-overwrite-ignore` to abort.
--abort:: `--abort`::
Abort the current conflict resolution process, and Abort the current conflict resolution process, and
try to reconstruct the pre-merge state. If an autostash entry is try to reconstruct the pre-merge state. If an autostash entry is
present, apply it to the worktree. present, apply it to the worktree.
@@ -114,17 +114,17 @@ which case `git merge --abort` applies the stash entry to the worktree
whereas `git reset --merge` will save the stashed changes in the stash whereas `git reset --merge` will save the stashed changes in the stash
list. list.
--quit:: `--quit`::
Forget about the current merge in progress. Leave the index Forget about the current merge in progress. Leave the index
and the working tree as-is. If `MERGE_AUTOSTASH` is present, the and the working tree as-is. If `MERGE_AUTOSTASH` is present, the
stash entry will be saved to the stash list. stash entry will be saved to the stash list.
--continue:: `--continue`::
After a `git merge` stops due to conflicts you can conclude the After a `git merge` stops due to conflicts you can conclude the
merge by running `git merge --continue` (see "HOW TO RESOLVE merge by running `git merge --continue` (see "HOW TO RESOLVE
CONFLICTS" section below). CONFLICTS" section below).
<commit>...:: `<commit>...`::
Commits, usually other branch heads, to merge into our branch. Commits, usually other branch heads, to merge into our branch.
Specifying more than one commit will create a merge with Specifying more than one commit will create a merge with
more than two parents (affectionately called an Octopus merge). more than two parents (affectionately called an Octopus merge).
@@ -152,7 +152,7 @@ To avoid recording unrelated changes in the merge commit,
`git pull` and `git merge` will also abort if there are any changes `git pull` and `git merge` will also abort if there are any changes
registered in the index relative to the `HEAD` commit. (Special registered in the index relative to the `HEAD` commit. (Special
narrow exceptions to this rule may exist depending on which merge narrow exceptions to this rule may exist depending on which merge
strategy is in use, but generally, the index must match HEAD.) strategy is in use, but generally, the index must match `HEAD`.)
If all named commits are already ancestors of `HEAD`, `git merge` If all named commits are already ancestors of `HEAD`, `git merge`
will exit early with the message "Already up to date." will exit early with the message "Already up to date."
@@ -195,11 +195,11 @@ happens:
stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
can inspect the stages with `git ls-files -u`). The working can inspect the stages with `git ls-files -u`). The working
tree files contain the result of the merge operation; i.e. 3-way tree files contain the result of the merge operation; i.e. 3-way
merge results with familiar conflict markers `<<<` `===` `>>>`. merge results with familiar conflict markers +<<<+ `===` +>>>+.
5. A ref named `AUTO_MERGE` is written, pointing to a tree 5. A ref named `AUTO_MERGE` is written, pointing to a tree
corresponding to the current content of the working tree (including corresponding to the current content of the working tree (including
conflict markers for textual conflicts). Note that this ref is only conflict markers for textual conflicts). Note that this ref is only
written when the 'ort' merge strategy is used (the default). written when the `ort` merge strategy is used (the default).
6. No other changes are made. In particular, the local 6. No other changes are made. In particular, the local
modifications you had before you started merge will stay the modifications you had before you started merge will stay the
same and the index entries for them stay as they were, same and the index entries for them stay as they were,
@@ -231,7 +231,6 @@ git merge v1.2.3^0
git merge --ff-only v1.2.3 git merge --ff-only v1.2.3
---- ----
HOW CONFLICTS ARE PRESENTED HOW CONFLICTS ARE PRESENTED
--------------------------- ---------------------------
@@ -260,7 +259,7 @@ And here is another line that is cleanly resolved or unmodified.
------------ ------------
The area where a pair of conflicting changes happened is marked with markers The area where a pair of conflicting changes happened is marked with markers
`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======` +<<<<<<<+, `=======`, and +>>>>>>>+. The part before the `=======`
is typically your side, and the part afterwards is typically their side. 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 The default format does not show what the original said in the conflicting
@@ -270,7 +269,7 @@ side wants to say it is hard and you'd prefer to go shopping, while the
other side wants to claim it is easy. other side wants to claim it is easy.
An alternative style can be used by setting the `merge.conflictStyle` An alternative style can be used by setting the `merge.conflictStyle`
configuration variable to either "diff3" or "zdiff3". In "diff3" configuration variable to either `diff3` or `zdiff3`. In `diff3`
style, the above conflict may look like this: style, the above conflict may look like this:
------------ ------------
@@ -290,7 +289,7 @@ Git makes conflict resolution easy.
And here is another line that is cleanly resolved or unmodified. And here is another line that is cleanly resolved or unmodified.
------------ ------------
while in "zdiff3" style, it may look like this: while in `zdiff3` style, it may look like this:
------------ ------------
Here are lines that are either unchanged from the common Here are lines that are either unchanged from the common
@@ -308,8 +307,8 @@ Git makes conflict resolution easy.
And here is another line that is cleanly resolved or unmodified. And here is another line that is cleanly resolved or unmodified.
------------ ------------
In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses
another `|||||||` marker that is followed by the original text. You can 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 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 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 positive attitude. You can sometimes come up with a better resolution by
@@ -390,8 +389,8 @@ include::merge-strategies.adoc[]
CONFIGURATION CONFIGURATION
------------- -------------
branch.<name>.mergeOptions:: `branch.<name>.mergeOptions`::
Sets default options for merging into branch <name>. The syntax and Sets default options for merging into branch _<name>_. The syntax and
supported options are the same as those of `git merge`, but option supported options are the same as those of `git merge`, but option
values containing whitespace characters are currently not supported. values containing whitespace characters are currently not supported.

62
Documentation/git-mergetool.adoc
View File

@@ -7,95 +7,95 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts
SYNOPSIS SYNOPSIS
-------- --------
[verse] [synopsis]
'git mergetool' [--tool=<tool>] [-y | --[no-]prompt] [<file>...] git mergetool [--tool=<tool>] [-y | --[no-]prompt] [<file>...]
DESCRIPTION DESCRIPTION
----------- -----------
Use `git mergetool` to run one of several merge utilities to resolve Use `git mergetool` to run one of several merge utilities to resolve
merge conflicts. It is typically run after 'git merge'. merge conflicts. It is typically run after `git merge`.
If one or more <file> parameters are given, the merge tool program will If one or more <file> parameters are given, the merge tool program will
be run to resolve differences in each file (skipping those without be run to resolve differences in each file (skipping those without
conflicts). Specifying a directory will include all unresolved files in conflicts). Specifying a directory will include all unresolved files in
that path. If no <file> names are specified, 'git mergetool' will run that path. If no _<file>_ names are specified, `git mergetool` will run
the merge tool program on every file with merge conflicts. the merge tool program on every file with merge conflicts.
OPTIONS OPTIONS
------- -------
-t <tool>:: `-t <tool>`::
--tool=<tool>:: `--tool=<tool>`::
Use the merge resolution program specified by <tool>. Use the merge resolution program specified by _<tool>_.
Valid values include emerge, gvimdiff, kdiff3, Valid values include `emerge`, `gvimdiff`, `kdiff3`,
meld, vimdiff, and tortoisemerge. Run `git mergetool --tool-help` `meld`, `vimdiff`, and `tortoisemerge`. Run `git mergetool --tool-help`
for the list of valid <tool> settings. for the list of valid _<tool>_ settings.
+ +
If a merge resolution program is not specified, 'git mergetool' If a merge resolution program is not specified, `git mergetool`
will use the configuration variable `merge.tool`. If the will use the configuration variable `merge.tool`. If the
configuration variable `merge.tool` is not set, 'git mergetool' configuration variable `merge.tool` is not set, `git mergetool`
will pick a suitable default. will pick a suitable default.
+ +
You can explicitly provide a full path to the tool by setting the You can explicitly provide a full path to the tool by setting the
configuration variable `mergetool.<tool>.path`. For example, you configuration variable `mergetool.<tool>.path`. For example, you
can configure the absolute path to kdiff3 by setting can configure the absolute path to kdiff3 by setting
`mergetool.kdiff3.path`. Otherwise, 'git mergetool' assumes the `mergetool.kdiff3.path`. Otherwise, `git mergetool` assumes the
tool is available in PATH. tool is available in `$PATH`.
+ +
Instead of running one of the known merge tool programs, Instead of running one of the known merge tool programs,
'git mergetool' can be customized to run an alternative program `git mergetool` can be customized to run an alternative program
by specifying the command line to invoke in a configuration by specifying the command line to invoke in a configuration
variable `mergetool.<tool>.cmd`. variable `mergetool.<tool>.cmd`.
+ +
When 'git mergetool' is invoked with this tool (either through the When `git mergetool` is invoked with this tool (either through the
`-t` or `--tool` option or the `merge.tool` configuration `-t` or `--tool` option or the `merge.tool` configuration
variable), the configured command line will be invoked with `$BASE` variable), the configured command line will be invoked with `BASE`
set to the name of a temporary file containing the common base for set to the name of a temporary file containing the common base for
the merge, if available; `$LOCAL` set to the name of a temporary the merge, if available; `LOCAL` set to the name of a temporary
file containing the contents of the file on the current branch; file containing the contents of the file on the current branch;
`$REMOTE` set to the name of a temporary file containing the `REMOTE` set to the name of a temporary file containing the
contents of the file to be merged, and `$MERGED` set to the name contents of the file to be merged, and `MERGED` set to the name
of the file to which the merge tool should write the result of the of the file to which the merge tool should write the result of the
merge resolution. merge resolution.
+ +
If the custom merge tool correctly indicates the success of a If the custom merge tool correctly indicates the success of a
merge resolution with its exit code, then the configuration merge resolution with its exit code, then the configuration
variable `mergetool.<tool>.trustExitCode` can be set to `true`. variable `mergetool.<tool>.trustExitCode` can be set to `true`.
Otherwise, 'git mergetool' will prompt the user to indicate the Otherwise, `git mergetool` will prompt the user to indicate the
success of the resolution after the custom tool has exited. success of the resolution after the custom tool has exited.
--tool-help:: `--tool-help`::
Print a list of merge tools that may be used with `--tool`. Print a list of merge tools that may be used with `--tool`.
-y:: `-y`::
--no-prompt:: `--no-prompt`::
Don't prompt before each invocation of the merge resolution Don't prompt before each invocation of the merge resolution
program. program.
This is the default if the merge resolution program is This is the default if the merge resolution program is
explicitly specified with the `--tool` option or with the explicitly specified with the `--tool` option or with the
`merge.tool` configuration variable. `merge.tool` configuration variable.
--prompt:: `--prompt`::
Prompt before each invocation of the merge resolution program Prompt before each invocation of the merge resolution program
to give the user a chance to skip the path. to give the user a chance to skip the path.
-g:: `-g`::
--gui:: `--gui`::
When 'git-mergetool' is invoked with the `-g` or `--gui` option, When `git-mergetool` is invoked with the `-g` or `--gui` option,
the default merge tool will be read from the configured the default merge tool will be read from the configured
`merge.guitool` variable instead of `merge.tool`. If `merge.guitool` variable instead of `merge.tool`. If
`merge.guitool` is not set, we will fallback to the tool `merge.guitool` is not set, we will fallback to the tool
configured under `merge.tool`. This may be autoselected using configured under `merge.tool`. This may be autoselected using
the configuration variable `mergetool.guiDefault`. the configuration variable `mergetool.guiDefault`.
--no-gui:: `--no-gui`::
This overrides a previous `-g` or `--gui` setting or This overrides a previous `-g` or `--gui` setting or
`mergetool.guiDefault` configuration and reads the default merge `mergetool.guiDefault` configuration and reads the default merge
tool from the configured `merge.tool` variable. tool from the configured `merge.tool` variable.
-O<orderfile>:: `-O<orderfile>`::
Process files in the order specified in the Process files in the order specified in the
<orderfile>, which has one shell glob pattern per line. _<orderfile>_, which has one shell glob pattern per line.
This overrides the `diff.orderFile` configuration variable This overrides the `diff.orderFile` configuration variable
(see linkgit:git-config[1]). To cancel `diff.orderFile`, (see linkgit:git-config[1]). To cancel `diff.orderFile`,
use `-O/dev/null`. use `-O/dev/null`.

112
Documentation/git-switch.adoc
View File

@@ -7,11 +7,11 @@ git-switch - Switch branches
SYNOPSIS SYNOPSIS
-------- --------
[verse] [synopsis]
'git switch' [<options>] [--no-guess] <branch> git switch [<options>] [--no-guess] <branch>
'git switch' [<options>] --detach [<start-point>] git switch [<options>] --detach [<start-point>]
'git switch' [<options>] (-c|-C) <new-branch> [<start-point>] git switch [<options>] (-c|-C) <new-branch> [<start-point>]
'git switch' [<options>] --orphan <new-branch> git switch [<options>] --orphan <new-branch>
DESCRIPTION DESCRIPTION
----------- -----------
@@ -33,33 +33,33 @@ THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
OPTIONS OPTIONS
------- -------
<branch>:: _<branch>_::
Branch to switch to. Branch to switch to.
<new-branch>:: _<new-branch>_::
Name for the new branch. Name for the new branch.
<start-point>:: _<start-point>_::
The starting point for the new branch. Specifying a The starting point for the new branch. Specifying a
`<start-point>` allows you to create a branch based on some _<start-point>_ allows you to create a branch based on some
other point in history than where HEAD currently points. (Or, other point in history than where `HEAD` currently points. (Or,
in the case of `--detach`, allows you to inspect and detach in the case of `--detach`, allows you to inspect and detach
from some other point.) from some other point.)
+ +
You can use the `@{-N}` syntax to refer to the N-th last You can use the `@{-<N>}` syntax to refer to the _<N>_-th last
branch/commit switched to using "git switch" or "git checkout" branch/commit switched to using `git switch` or `git checkout`
operation. You may also specify `-` which is synonymous to `@{-1}`. operation. You may also specify `-` which is synonymous to `@{-1}`.
This is often used to switch quickly between two branches, or to undo This is often used to switch quickly between two branches, or to undo
a branch switch by mistake. a branch switch by mistake.
+ +
As a special case, you may use `A...B` as a shortcut for the merge As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the merge
base of `A` and `B` if there is exactly one merge base. You can leave base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can leave
out at most one of `A` and `B`, in which case it defaults to `HEAD`. out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
-c <new-branch>:: `-c <new-branch>`::
--create <new-branch>:: `--create <new-branch>`::
Create a new branch named `<new-branch>` starting at Create a new branch named _<new-branch>_ starting at
`<start-point>` before switching to the branch. This is the _<start-point>_ before switching to the branch. This is the
transactional equivalent of transactional equivalent of
+ +
------------ ------------
@@ -67,32 +67,32 @@ $ git branch <new-branch>
$ git switch <new-branch> $ git switch <new-branch>
------------ ------------
+ +
that is to say, the branch is not reset/created unless "git switch" is that is to say, the branch is not reset/created unless `git switch` is
successful (e.g., when the branch is in use in another worktree, not successful (e.g., when the branch is in use in another worktree, not
just the current branch stays the same, but the branch is not reset to just the current branch stays the same, but the branch is not reset to
the start-point, either). the start-point, either).
-C <new-branch>:: `-C <new-branch>`::
--force-create <new-branch>:: `--force-create <new-branch>`::
Similar to `--create` except that if `<new-branch>` already Similar to `--create` except that if _<new-branch>_ already
exists, it will be reset to `<start-point>`. This is a exists, it will be reset to _<start-point>_. This is a
convenient shortcut for: convenient shortcut for:
+ +
------------ ------------
$ git branch -f <new-branch> $ git branch -f _<new-branch>_
$ git switch <new-branch> $ git switch _<new-branch>_
------------ ------------
-d:: `-d`::
--detach:: `--detach`::
Switch to a commit for inspection and discardable Switch to a commit for inspection and discardable
experiments. See the "DETACHED HEAD" section in experiments. See the "DETACHED HEAD" section in
linkgit:git-checkout[1] for details. linkgit:git-checkout[1] for details.
--guess:: `--guess`::
--no-guess:: `--no-guess`::
If `<branch>` is not found but there does exist a tracking If _<branch>_ is not found but there does exist a tracking
branch in exactly one remote (call it `<remote>`) with a branch in exactly one remote (call it _<remote>_) with a
matching name, treat as equivalent to matching name, treat as equivalent to
+ +
------------ ------------
@@ -101,9 +101,9 @@ $ git switch -c <branch> --track <remote>/<branch>
+ +
If the branch exists in multiple remotes and one of them is named by If the branch exists in multiple remotes and one of them is named by
the `checkout.defaultRemote` configuration variable, we'll use that the `checkout.defaultRemote` configuration variable, we'll use that
one for the purposes of disambiguation, even if the `<branch>` isn't one for the purposes of disambiguation, even if the _<branch>_ isn't
unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin` unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin`
to always checkout remote branches from there if `<branch>` is to always checkout remote branches from there if _<branch>_ is
ambiguous but exists on the 'origin' remote. See also ambiguous but exists on the 'origin' remote. See also
`checkout.defaultRemote` in linkgit:git-config[1]. `checkout.defaultRemote` in linkgit:git-config[1].
+ +
@@ -112,19 +112,19 @@ ambiguous but exists on the 'origin' remote. See also
The default behavior can be set via the `checkout.guess` configuration The default behavior can be set via the `checkout.guess` configuration
variable. variable.
-f:: `-f`::
--force:: `--force`::
An alias for `--discard-changes`. An alias for `--discard-changes`.
--discard-changes:: `--discard-changes`::
Proceed even if the index or the working tree differs from Proceed even if the index or the working tree differs from
`HEAD`. Both the index and working tree are restored to match `HEAD`. Both the index and working tree are restored to match
the switching target. If `--recurse-submodules` is specified, the switching target. If `--recurse-submodules` is specified,
submodule content is also restored to match the switching submodule content is also restored to match the switching
target. This is used to throw away local changes. target. This is used to throw away local changes.
-m:: `-m`::
--merge:: `--merge`::
If you have local modifications to one or more files that are If you have local modifications to one or more files that are
different between the current branch and the branch to which different between the current branch and the branch to which
you are switching, the command refuses to switch branches in you are switching, the command refuses to switch branches in
@@ -138,25 +138,25 @@ paths are left unmerged, and you need to resolve the conflicts
and mark the resolved paths with `git add` (or `git rm` if the merge and mark the resolved paths with `git add` (or `git rm` if the merge
should result in deletion of the path). should result in deletion of the path).
--conflict=<style>:: `--conflict=<style>`::
The same as `--merge` option above, but changes the way the The same as `--merge` option above, but changes the way the
conflicting hunks are presented, overriding the conflicting hunks are presented, overriding the
`merge.conflictStyle` configuration variable. Possible values are `merge.conflictStyle` configuration variable. Possible values are
"merge" (default), "diff3", and "zdiff3". `merge` (default), `diff3`, and `zdiff3`.
-q:: `-q`::
--quiet:: `--quiet`::
Quiet, suppress feedback messages. Quiet, suppress feedback messages.
--progress:: `--progress`::
--no-progress:: `--no-progress`::
Progress status is reported on the standard error stream Progress status is reported on the standard error stream
by default when it is attached to a terminal, unless `--quiet` by default when it is attached to a terminal, unless `--quiet`
is specified. This flag enables progress reporting even if not is specified. This flag enables progress reporting even if not
attached to a terminal, regardless of `--quiet`. attached to a terminal, regardless of `--quiet`.
-t:: `-t`::
--track [direct|inherit]:: `--track[ (direct|inherit)]`::
When creating a new branch, set up "upstream" configuration. When creating a new branch, set up "upstream" configuration.
`-c` is implied. See `--track` in linkgit:git-branch[1] for `-c` is implied. See `--track` in linkgit:git-branch[1] for
details. details.
@@ -171,22 +171,22 @@ given name has no slash, or the above guessing results in an empty
name, the guessing is aborted. You can explicitly give a name with name, the guessing is aborted. You can explicitly give a name with
`-c` in such a case. `-c` in such a case.
--no-track:: `--no-track`::
Do not set up "upstream" configuration, even if the Do not set up "upstream" configuration, even if the
`branch.autoSetupMerge` configuration variable is true. `branch.autoSetupMerge` configuration variable is true.
--orphan <new-branch>:: `--orphan <new-branch>`::
Create a new unborn branch, named `<new-branch>`. All Create a new unborn branch, named _<new-branch>_. All
tracked files are removed. tracked files are removed.
--ignore-other-worktrees:: `--ignore-other-worktrees`::
`git switch` refuses when the wanted ref is already `git switch` refuses when the wanted ref is already
checked out by another worktree. This option makes it check checked out by another worktree. This option makes it check
the ref out anyway. In other words, the ref can be held by the ref out anyway. In other words, the ref can be held by
more than one worktree. more than one worktree.
--recurse-submodules:: `--recurse-submodules`::
--no-recurse-submodules:: `--no-recurse-submodules`::
Using `--recurse-submodules` will update the content of all Using `--recurse-submodules` will update the content of all
active submodules according to the commit recorded in the active submodules according to the commit recorded in the
superproject. If nothing (or `--no-recurse-submodules`) is superproject. If nothing (or `--no-recurse-submodules`) is
@@ -239,7 +239,7 @@ $ git switch -
------------ ------------
You can grow a new branch from any commit. For example, switch to You can grow a new branch from any commit. For example, switch to
"HEAD~3" and create branch "fixup": "`HEAD~3`" and create branch "`fixup`":
------------ ------------
$ git switch -c fixup HEAD~3 $ git switch -c fixup HEAD~3
@@ -251,8 +251,8 @@ name:
------------ ------------
$ git switch new-topic $ git switch new-topic
Branch 'new-topic' set up to track remote branch 'new-topic' from 'origin' Branch `new-topic` set up to track remote branch `new-topic` from `origin`
Switched to a new branch 'new-topic' Switched to a new branch `new-topic`
------------ ------------
To check out commit `HEAD~3` for temporary inspection or experiment To check out commit `HEAD~3` for temporary inspection or experiment

110
Documentation/merge-options.adoc
View File

@@ -1,23 +1,23 @@
--commit:: `--commit`::
--no-commit:: `--no-commit`::
Perform the merge and commit the result. This option can Perform the merge and commit the result. This option can
be used to override --no-commit. be used to override `--no-commit`.
ifdef::git-pull[] ifdef::git-pull[]
Only useful when merging. Only useful when merging.
endif::git-pull[] endif::git-pull[]
+ +
With --no-commit perform the merge and stop just before creating With `--no-commit` perform the merge and stop just before creating
a merge commit, to give the user a chance to inspect and further a merge commit, to give the user a chance to inspect and further
tweak the merge result before committing. tweak the merge result before committing.
+ +
Note that fast-forward updates do not create a merge commit and Note that fast-forward updates do not create a merge commit and
therefore there is no way to stop those merges with --no-commit. therefore there is no way to stop those merges with `--no-commit`.
Thus, if you want to ensure your branch is not changed or updated Thus, if you want to ensure your branch is not changed or updated
by the merge command, use --no-ff with --no-commit. by the merge command, use `--no-ff` with `--no-commit`.
--edit:: `--edit`::
-e:: `-e`::
--no-edit:: `--no-edit`::
Invoke an editor before committing successful mechanical merge to Invoke an editor before committing successful mechanical merge to
further edit the auto-generated merge message, so that the user further edit the auto-generated merge message, so that the user
can explain and justify the merge. The `--no-edit` option can be can explain and justify the merge. The `--no-edit` option can be
@@ -35,17 +35,17 @@ they run `git merge`. To make it easier to adjust such scripts to the
updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be
set to `no` at the beginning of them. set to `no` at the beginning of them.
--cleanup=<mode>:: `--cleanup=<mode>`::
This option determines how the merge message will be cleaned up before This option determines how the merge message will be cleaned up before
committing. See linkgit:git-commit[1] for more details. In addition, if committing. See linkgit:git-commit[1] for more details. In addition, if
the '<mode>' is given a value of `scissors`, scissors will be appended the _<mode>_ is given a value of `scissors`, scissors will be appended
to `MERGE_MSG` before being passed on to the commit machinery in the to `MERGE_MSG` before being passed on to the commit machinery in the
case of a merge conflict. case of a merge conflict.
ifdef::git-merge[] ifdef::git-merge[]
--ff:: `--ff`::
--no-ff:: `--no-ff`::
--ff-only:: `--ff-only`::
Specifies how a merge is handled when the merged-in history is Specifies how a merge is handled when the merged-in history is
already a descendant of the current history. `--ff` is the already a descendant of the current history. `--ff` is the
default unless merging an annotated (and possibly signed) tag default unless merging an annotated (and possibly signed) tag
@@ -53,13 +53,13 @@ ifdef::git-merge[]
hierarchy, in which case `--no-ff` is assumed. hierarchy, in which case `--no-ff` is assumed.
endif::git-merge[] endif::git-merge[]
ifdef::git-pull[] ifdef::git-pull[]
--ff-only:: `--ff-only`::
Only update to the new history if there is no divergent local Only update to the new history if there is no divergent local
history. This is the default when no method for reconciling history. This is the default when no method for reconciling
divergent histories is provided (via the --rebase=* flags). divergent histories is provided (via the --rebase=* flags).
--ff:: `--ff`::
--no-ff:: `--no-ff`::
When merging rather than rebasing, specifies how a merge is When merging rather than rebasing, specifies how a merge is
handled when the merged-in history is already a descendant of handled when the merged-in history is already a descendant of
the current history. If merging is requested, `--ff` is the the current history. If merging is requested, `--ff` is the
@@ -81,40 +81,40 @@ With `--ff-only`, resolve the merge as a fast-forward when possible.
When not possible, refuse to merge and exit with a non-zero status. When not possible, refuse to merge and exit with a non-zero status.
endif::git-merge[] endif::git-merge[]
-S[<keyid>]:: `-S[<key-id>]`::
--gpg-sign[=<keyid>]:: `--gpg-sign[=<key-id>]`::
--no-gpg-sign:: `--no-gpg-sign`::
GPG-sign the resulting merge commit. The `keyid` argument is GPG-sign the resulting merge commit. The _<key-id>_ argument is
optional and defaults to the committer identity; if specified, optional and defaults to the committer identity; if specified,
it must be stuck to the option without a space. `--no-gpg-sign` it must be stuck to the option without a space. `--no-gpg-sign`
is useful to countermand both `commit.gpgSign` configuration variable, is useful to countermand both `commit.gpgSign` configuration variable,
and earlier `--gpg-sign`. and earlier `--gpg-sign`.
--log[=<n>]:: `--log[=<n>]`::
--no-log:: `--no-log`::
In addition to branch names, populate the log message with In addition to branch names, populate the log message with
one-line descriptions from at most <n> actual commits that are being one-line descriptions from at most _<n>_ actual commits that are being
merged. See also linkgit:git-fmt-merge-msg[1]. merged. See also linkgit:git-fmt-merge-msg[1].
ifdef::git-pull[] ifdef::git-pull[]
Only useful when merging. Only useful when merging.
endif::git-pull[] endif::git-pull[]
+ +
With --no-log do not list one-line descriptions from the With `--no-log` do not list one-line descriptions from the
actual commits being merged. actual commits being merged.
include::signoff-option.adoc[] include::signoff-option.adoc[]
--stat:: `--stat`::
-n:: `-n`::
--no-stat:: `--no-stat`::
Show a diffstat at the end of the merge. The diffstat is also Show a diffstat at the end of the merge. The diffstat is also
controlled by the configuration option merge.stat. controlled by the configuration option merge.stat.
+ +
With -n or --no-stat do not show a diffstat at the end of the With `-n` or `--no-stat` do not show a diffstat at the end of the
merge. merge.
--squash:: `--squash`::
--no-squash:: `--no-squash`::
Produce the working tree and index state as if a real merge Produce the working tree and index state as if a real merge
happened (except for the merge information), but do not actually happened (except for the merge information), but do not actually
make a commit, move the `HEAD`, or record `$GIT_DIR/MERGE_HEAD` make a commit, move the `HEAD`, or record `$GIT_DIR/MERGE_HEAD`
@@ -123,16 +123,16 @@ merge.
the current branch whose effect is the same as merging another the current branch whose effect is the same as merging another
branch (or more in case of an octopus). branch (or more in case of an octopus).
+ +
With --no-squash perform the merge and commit the result. This With `--no-squash` perform the merge and commit the result. This
option can be used to override --squash. option can be used to override `--squash`.
+ +
With --squash, --commit is not allowed, and will fail. With `--squash`, `--commit` is not allowed, and will fail.
ifdef::git-pull[] ifdef::git-pull[]
+ +
Only useful when merging. Only useful when merging.
endif::git-pull[] endif::git-pull[]
--[no-]verify:: `--[no-]verify`::
By default, the pre-merge and commit-msg hooks are run. By default, the pre-merge and commit-msg hooks are run.
When `--no-verify` is given, these are bypassed. When `--no-verify` is given, these are bypassed.
See also linkgit:githooks[5]. See also linkgit:githooks[5].
@@ -140,21 +140,21 @@ ifdef::git-pull[]
Only useful when merging. Only useful when merging.
endif::git-pull[] endif::git-pull[]
-s <strategy>:: `-s <strategy>`::
--strategy=<strategy>:: `--strategy=<strategy>`::
Use the given merge strategy; can be supplied more than Use the given merge strategy; can be supplied more than
once to specify them in the order they should be tried. once to specify them in the order they should be tried.
If there is no `-s` option, a built-in list of strategies If there is no `-s` option, a built-in list of strategies
is used instead (`ort` when merging a single head, is used instead (`ort` when merging a single head,
`octopus` otherwise). `octopus` otherwise).
-X <option>:: `-X <option>`::
--strategy-option=<option>:: `--strategy-option=<option>`::
Pass merge strategy specific option through to the merge Pass merge strategy specific option through to the merge
strategy. strategy.
--verify-signatures:: `--verify-signatures`::
--no-verify-signatures:: `--no-verify-signatures`::
Verify that the tip commit of the side branch being merged is Verify that the tip commit of the side branch being merged is
signed with a valid key, i.e. a key that has a valid uid: in the signed with a valid key, i.e. a key that has a valid uid: in the
default trust model, this means the signing key has been signed by default trust model, this means the signing key has been signed by
@@ -165,22 +165,22 @@ ifdef::git-pull[]
Only useful when merging. Only useful when merging.
endif::git-pull[] endif::git-pull[]
--summary:: `--summary`::
--no-summary:: `--no-summary`::
Synonyms to --stat and --no-stat; these are deprecated and will be Synonyms to `--stat` and `--no-stat`; these are deprecated and will be
removed in the future. removed in the future.
ifndef::git-pull[] ifndef::git-pull[]
-q:: `-q`::
--quiet:: `--quiet`::
Operate quietly. Implies --no-progress. Operate quietly. Implies `--no-progress`.
-v:: `-v`::
--verbose:: `--verbose`::
Be verbose. Be verbose.
--progress:: `--progress`::
--no-progress:: `--no-progress`::
Turn progress on/off explicitly. If neither is specified, Turn progress on/off explicitly. If neither is specified,
progress is shown if standard error is connected to a terminal. progress is shown if standard error is connected to a terminal.
Note that not all merge strategies may support progress Note that not all merge strategies may support progress
@@ -188,8 +188,8 @@ ifndef::git-pull[]
endif::git-pull[] endif::git-pull[]
--autostash:: `--autostash`::
--no-autostash:: `--no-autostash`::
Automatically create a temporary stash entry before the operation Automatically create a temporary stash entry before the operation
begins, record it in the ref `MERGE_AUTOSTASH` begins, record it in the ref `MERGE_AUTOSTASH`
and apply it after the operation ends. This means and apply it after the operation ends. This means
@@ -197,13 +197,13 @@ endif::git-pull[]
with care: the final stash application after a successful with care: the final stash application after a successful
merge might result in non-trivial conflicts. merge might result in non-trivial conflicts.
--allow-unrelated-histories:: `--allow-unrelated-histories`::
By default, `git merge` command refuses to merge histories By default, `git merge` command refuses to merge histories
that do not share a common ancestor. This option can be that do not share a common ancestor. This option can be
used to override this safety when merging histories of two used to override this safety when merging histories of two
projects that started their lives independently. As that is projects that started their lives independently. As that is
a very rare occasion, no configuration variable to enable a very rare occasion, no configuration variable to enable
this by default exists and will not be added. this by default exists or will be added.
ifdef::git-pull[] ifdef::git-pull[]
+ +
Only useful when merging. Only useful when merging.

58
Documentation/merge-strategies.adoc
View File

@@ -6,7 +6,7 @@ backend 'merge strategies' to be chosen with `-s` option. Some strategies
can also take their own options, which can be passed by giving `-X<option>` can also take their own options, which can be passed by giving `-X<option>`
arguments to `git merge` and/or `git pull`. arguments to `git merge` and/or `git pull`.
ort:: `ort`::
This is the default merge strategy when pulling or merging one This is the default merge strategy when pulling or merging one
branch. This strategy can only resolve two heads using a branch. This strategy can only resolve two heads using a
3-way merge algorithm. When there is more than one common 3-way merge algorithm. When there is more than one common
@@ -29,26 +29,26 @@ descendant. Otherwise, Git will treat this case as a conflict, suggesting
as a resolution a submodule commit that is descendant of the conflicting as a resolution a submodule commit that is descendant of the conflicting
ones, if one exists. ones, if one exists.
+ +
The 'ort' strategy can take the following options: The `ort` strategy can take the following options:
ours;; `ours`;;
This option forces conflicting hunks to be auto-resolved cleanly by This option forces conflicting hunks to be auto-resolved cleanly by
favoring 'our' version. Changes from the other tree that do not favoring 'our' version. Changes from the other tree that do not
conflict with our side are reflected in the merge result. conflict with our side are reflected in the merge result.
For a binary file, the entire contents are taken from our side. For a binary file, the entire contents are taken from our side.
+ +
This should not be confused with the 'ours' merge strategy, which does not This should not be confused with the `ours` merge strategy, which does not
even look at what the other tree contains at all. It discards everything even look at what the other tree contains at all. It discards everything
the other tree did, declaring 'our' history contains all that happened in it. the other tree did, declaring 'our' history contains all that happened in it.
theirs;; `theirs`;;
This is the opposite of 'ours'; note that, unlike 'ours', there is This is the opposite of `ours`; note that, unlike `ours`, there is
no 'theirs' merge strategy to confuse this merge option with. no `theirs` merge strategy to confuse this merge option with.
ignore-space-change;; `ignore-space-change`;;
ignore-all-space;; `ignore-all-space`;;
ignore-space-at-eol;; `ignore-space-at-eol`;;
ignore-cr-at-eol;; `ignore-cr-at-eol`;;
Treats lines with the indicated type of whitespace change as Treats lines with the indicated type of whitespace change as
unchanged for the sake of a three-way merge. Whitespace unchanged for the sake of a three-way merge. Whitespace
changes mixed with other changes to a line are not ignored. changes mixed with other changes to a line are not ignored.
@@ -61,7 +61,7 @@ ignore-cr-at-eol;;
version includes a substantial change, 'their' version is used; version includes a substantial change, 'their' version is used;
* Otherwise, the merge proceeds in the usual way. * Otherwise, the merge proceeds in the usual way.
renormalize;; `renormalize`;;
This runs a virtual check-out and check-in of all three stages This runs a virtual check-out and check-in of all three stages
of any file which needs a three-way merge. This option is of any file which needs a three-way merge. This option is
meant to be used when merging branches with different clean meant to be used when merging branches with different clean
@@ -69,31 +69,31 @@ renormalize;;
branches with differing checkin/checkout attributes" in branches with differing checkin/checkout attributes" in
linkgit:gitattributes[5] for details. linkgit:gitattributes[5] for details.
no-renormalize;; `no-renormalize`;;
Disables the `renormalize` option. This overrides the Disables the `renormalize` option. This overrides the
`merge.renormalize` configuration variable. `merge.renormalize` configuration variable.
find-renames[=<n>];; `find-renames[=<n>]`;;
Turn on rename detection, optionally setting the similarity Turn on rename detection, optionally setting the similarity
threshold. This is the default. This overrides the threshold. This is the default. This overrides the
'merge.renames' configuration variable. `merge.renames` configuration variable.
See also linkgit:git-diff[1] `--find-renames`. See also linkgit:git-diff[1] `--find-renames`.
rename-threshold=<n>;; `rename-threshold=<n>`;;
Deprecated synonym for `find-renames=<n>`. Deprecated synonym for `find-renames=<n>`.
no-renames;; `no-renames`;;
Turn off rename detection. This overrides the `merge.renames` Turn off rename detection. This overrides the `merge.renames`
configuration variable. configuration variable.
See also linkgit:git-diff[1] `--no-renames`. See also linkgit:git-diff[1] `--no-renames`.
histogram;; `histogram`;;
Deprecated synonym for `diff-algorithm=histogram`. Deprecated synonym for `diff-algorithm=histogram`.
patience;; `patience`;;
Deprecated synonym for `diff-algorithm=patience`. Deprecated synonym for `diff-algorithm=patience`.
diff-algorithm=[histogram|minimal|myers|patience];; `diff-algorithm=(histogram|minimal|myers|patience)`;;
Use a different diff algorithm while merging, which can help Use a different diff algorithm while merging, which can help
avoid mismerges that occur due to unimportant matching lines avoid mismerges that occur due to unimportant matching lines
(such as braces from distinct functions). See also (such as braces from distinct functions). See also
@@ -101,49 +101,49 @@ diff-algorithm=[histogram|minimal|myers|patience];;
defaults to `diff-algorithm=histogram`, while regular diffs defaults to `diff-algorithm=histogram`, while regular diffs
currently default to the `diff.algorithm` config setting. currently default to the `diff.algorithm` config setting.
subtree[=<path>];; `subtree[=<path>]`;;
This option is a more advanced form of 'subtree' strategy, where This option is a more advanced form of 'subtree' strategy, where
the strategy makes a guess on how two trees must be shifted to the strategy makes a guess on how two trees must be shifted to
match with each other when merging. Instead, the specified path match with each other when merging. Instead, the specified path
is prefixed (or stripped from the beginning) to make the shape of is prefixed (or stripped from the beginning) to make the shape of
two trees to match. two trees to match.
recursive:: `recursive`::
This is now a synonym for `ort`. It was an alternative This is now a synonym for `ort`. It was an alternative
implementation until v2.49.0, but was redirected to mean `ort` implementation until v2.49.0, but was redirected to mean `ort`
in v2.50.0. The previous recursive strategy was the default in v2.50.0. The previous recursive strategy was the default
strategy for resolving two heads from Git v0.99.9k until strategy for resolving two heads from Git v0.99.9k until
v2.33.0. v2.33.0.
resolve:: `resolve`::
This can only resolve two heads (i.e. the current branch This can only resolve two heads (i.e. the current branch
and another branch you pulled from) using a 3-way merge and another branch you pulled from) using a 3-way merge
algorithm. It tries to carefully detect criss-cross algorithm. It tries to carefully detect criss-cross
merge ambiguities. It does not handle renames. merge ambiguities. It does not handle renames.
octopus:: `octopus`::
This resolves cases with more than two heads, but refuses to do This resolves cases with more than two heads, but refuses to do
a complex merge that needs manual resolution. It is a complex merge that needs manual resolution. It is
primarily meant to be used for bundling topic branch primarily meant to be used for bundling topic branch
heads together. This is the default merge strategy when heads together. This is the default merge strategy when
pulling or merging more than one branch. pulling or merging more than one branch.
ours:: `ours`::
This resolves any number of heads, but the resulting tree of the This resolves any number of heads, but the resulting tree of the
merge is always that of the current branch head, effectively merge is always that of the current branch head, effectively
ignoring all changes from all other branches. It is meant to ignoring all changes from all other branches. It is meant to
be used to supersede old development history of side be used to supersede old development history of side
branches. Note that this is different from the -Xours option to branches. Note that this is different from the `-Xours` option to
the 'ort' merge strategy. the `ort` merge strategy.
subtree:: `subtree`::
This is a modified `ort` strategy. When merging trees A and This is a modified `ort` strategy. When merging trees A and
B, if B corresponds to a subtree of A, B is first adjusted to B, if B corresponds to a subtree of A, B is first adjusted to
match the tree structure of A, instead of reading the trees at match the tree structure of A, instead of reading the trees at
the same level. This adjustment is also done to the common the same level. This adjustment is also done to the common
ancestor tree. ancestor tree.
With the strategies that use 3-way merge (including the default, 'ort'), With the strategies that use 3-way merge (including the default, `ort`),
if a change is made on both branches, but later reverted on one of the if a change is made on both branches, but later reverted on one of the
branches, that change will be present in the merged result; some people find branches, that change will be present in the merged result; some people find
this behavior confusing. It occurs because only the heads and the merge base this behavior confusing. It occurs because only the heads and the merge base

16
Documentation/mergetools/vimdiff.adoc
View File

@@ -183,13 +183,13 @@ latter will be used as fallback if the variant-specific one is not set).
In addition, for backwards compatibility with previous Git versions, you can In addition, for backwards compatibility with previous Git versions, you can
also append `1`, `2` or `3` to either `vimdiff` or any of the variants (ex: also append `1`, `2` or `3` to either `vimdiff` or any of the variants (ex:
`vimdiff3`, `nvimdiff1`, etc...) to use a predefined layout. `vimdiff3`, `nvimdiff1`, etc...) to use a predefined layout.
In other words, using `--tool=[g,n,]vimdiffx` is the same as using In other words, using `--tool=[g|n]vimdiff<x>` is the same as using
`--tool=[g,n,]vimdiff` and setting configuration variable `--tool=[g|n]vimdiff` and setting configuration variable
`mergetool.[g,n,]vimdiff.layout` to... `mergetool.[g|n]vimdiff.layout` to...
* `x=1`: `"@LOCAL, REMOTE"` * `<x>=1`: `"@LOCAL, REMOTE"`
* `x=2`: `"LOCAL, MERGED, REMOTE"` * `<x>=2`: `"LOCAL, MERGED, REMOTE"`
* `x=3`: `"MERGED"` * `<x>=3`: `"MERGED"`
Example: using `--tool=gvimdiff2` will open `gvim` with three columns (LOCAL, Example: using `--tool=gvimdiff2` will open `gvim` with three columns (`LOCAL`,
MERGED and REMOTE). `MERGED` and `REMOTE`).

4
Documentation/rerere-options.adoc
View File

@@ -1,5 +1,5 @@
--rerere-autoupdate:: `--rerere-autoupdate`::
--no-rerere-autoupdate:: `--no-rerere-autoupdate`::
After the rerere mechanism reuses a recorded resolution on After the rerere mechanism reuses a recorded resolution on
the current conflict to update the files in the working the current conflict to update the files in the working
tree, allow it to also update the index with the result of tree, allow it to also update the index with the result of