diff --git a/Documentation/config/checkout.adoc b/Documentation/config/checkout.adoc index a3230229938055..e35d21296978fe 100644 --- a/Documentation/config/checkout.adoc +++ b/Documentation/config/checkout.adoc @@ -1,9 +1,9 @@ -checkout.defaultRemote:: +`checkout.defaultRemote`:: When you run `git checkout ` or `git switch ` and only have one remote, it may implicitly fall back on checking out and tracking e.g. `origin/`. This stops working as soon - as you have more than one remote with a `` + as you have more than one remote with a __ reference. This setting allows for setting the name of a preferred remote that should always win when it comes 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 linkgit:git-checkout[1] when `git checkout ` or `git switch ` -will checkout the `` branch on another remote, +will checkout the __ branch on another remote, and by linkgit:git-worktree[1] when `git worktree add` refers to a remote branch. This setting might be used for other checkout-like commands or functionality in the future. -checkout.guess:: +`checkout.guess`:: Provides the default value for the `--guess` or `--no-guess` option in `git checkout` and `git switch`. See 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 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 @@ -30,13 +30,13 @@ checkout.workers:: all commands that perform checkout. E.g. checkout, clone, reset, 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 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 well the parallel version performs. -checkout.thresholdForParallelism:: +`checkout.thresholdForParallelism`:: When running parallel checkout with a small number of files, the cost of subprocess spawning and inter-process communication might outweigh the parallelization gains. This setting allows you to define the minimum diff --git a/Documentation/config/fmt-merge-msg.adoc b/Documentation/config/fmt-merge-msg.adoc index 3fbf40e24f62ed..696ba0531ae122 100644 --- a/Documentation/config/fmt-merge-msg.adoc +++ b/Documentation/config/fmt-merge-msg.adoc @@ -1,19 +1,19 @@ -merge.branchdesc:: +`merge.branchdesc`:: In addition to branch names, populate the log message with the branch description text associated with them. Defaults to false. -merge.log:: +`merge.log`:: In addition to branch names, populate the log message with at most the specified number of one-line descriptions from the actual commits that are being merged. Defaults to false, and true is a synonym for 20. -merge.suppressDest:: +`merge.suppressDest`:: By adding a glob that matches the names of integration branches to this multi-valued configuration variable, the default merge message computed for merges into these - integration branches will omit "into " from + integration branches will omit "into __" from its title. + An element with an empty value can be used to clear the list diff --git a/Documentation/config/merge.adoc b/Documentation/config/merge.adoc index d2d0f21a712daf..86359f6dd2d904 100644 --- a/Documentation/config/merge.adoc +++ b/Documentation/config/merge.adoc @@ -1,9 +1,9 @@ -merge.conflictStyle:: +`merge.conflictStyle`:: Specify the style in which conflicted hunks are written out to 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. An alternate style, "diff3", adds a `|||||||` + a +>>>>>>>+ marker. An alternate style, "diff3", adds a +|||||||+ marker and the original text before the `=======` marker. The "merge" style tends to produce smaller conflict regions than diff3, 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 beginning or end of a conflict region. -merge.defaultToUpstream:: +`merge.defaultToUpstream`:: If merge is called without any commit argument, merge the upstream branches configured for the current branch by using their last observed values stored in their remote-tracking branches. The values of the `branch..merge` that name the - branches at the remote named by `branch..remote` + branches at the remote named by `branch..remote` are consulted, and then they are mapped via `remote..fetch` to their corresponding remote-tracking branches, and the tips of these tracking branches are merged. Defaults to true. -merge.ff:: +`merge.ff`:: By default, Git does not create an extra merge commit when merging a commit that is a descendant of the current commit. Instead, the 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 command line). -merge.verifySignatures:: - If true, this is equivalent to the --verify-signatures command +`merge.verifySignatures`:: + If true, this is equivalent to the `--verify-signatures` command line option. See linkgit:git-merge[1] for details. include::fmt-merge-msg.adoc[] -merge.renameLimit:: +`merge.renameLimit`:: The number of files to consider in the exhaustive portion of rename detection during a merge. If not specified, defaults - to the value of diff.renameLimit. If neither - merge.renameLimit nor diff.renameLimit are specified, + to the value of `diff.renameLimit`. If neither + `merge.renameLimit` nor `diff.renameLimit` are specified, currently defaults to 7000. This setting has no effect if rename detection is turned off. -merge.renames:: - Whether Git detects renames. If set to "false", rename detection - is disabled. If set to "true", basic rename detection is enabled. +`merge.renames`:: + Whether Git detects renames. If set to `false`, rename detection + is disabled. If set to `true`, basic rename detection is enabled. Defaults to the value of diff.renames. -merge.directoryRenames:: +`merge.directoryRenames`:: Whether Git detects directory renames, affecting what happens at 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. If merge.directoryRenames is set to "false", directory - 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 - moved into the new directory. If set to "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:: + history. Possible values are: ++ +-- +`false`;; Directory rename detection is disabled, meaning that such new files will be + left behind in the old directory. +`true`;; Directory rename detection is enabled, meaning that such new files will be + moved into the new directory. +`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`:: Tell Git that canonical representation of files in the 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 three-way content merge is needed, Git can convert the data recorded in commits to a canonical form before performing a @@ -76,35 +80,35 @@ merge.renormalize:: see section "Merging branches with differing checkin/checkout attributes" in linkgit:gitattributes[5]. -merge.stat:: - Whether to print the diffstat between ORIG_HEAD and the merge result +`merge.stat`:: + Whether to print the diffstat between `ORIG_HEAD` and the merge result at the end of the merge. True by default. -merge.autoStash:: - When set to true, automatically create a temporary stash entry +`merge.autoStash`:: + When set to `true`, automatically create a temporary stash entry before the operation begins, and apply it after the operation ends. This means that you can run merge on a dirty worktree. However, use with care: the final stash application after a successful merge might result in non-trivial conflicts. This option can be overridden by the `--no-autostash` and `--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]. The list below shows the valid built-in values. Any other value is treated as a custom merge tool and requires - that a corresponding mergetool..cmd variable is defined. + that a corresponding `mergetool..cmd` variable is defined. -merge.guitool:: +`merge.guitool`:: 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 - corresponding mergetool..cmd variable is defined. + corresponding `mergetool..cmd` variable is defined. include::{build_dir}/mergetools-merge.adoc[] -merge.verbosity:: +`merge.verbosity`:: Controls the amount of output shown by the recursive merge strategy. Level 0 outputs nothing except a final error message if conflicts were detected. Level 1 outputs only @@ -112,15 +116,15 @@ merge.verbosity:: above outputs debugging information. The default is level 2. Can be overridden by the `GIT_MERGE_VERBOSITY` environment variable. -merge..name:: +`merge..name`:: Defines a human-readable name for a custom low-level merge driver. See linkgit:gitattributes[5] for details. -merge..driver:: +`merge..driver`:: Defines the command that implements a custom low-level merge driver. See linkgit:gitattributes[5] for details. -merge..recursive:: +`merge..recursive`:: Names a low-level merge driver to be used when performing an internal merge between common ancestors. See linkgit:gitattributes[5] for details. diff --git a/Documentation/config/mergetool.adoc b/Documentation/config/mergetool.adoc index 00bf665aa09bf3..6be506145c150b 100644 --- a/Documentation/config/mergetool.adoc +++ b/Documentation/config/mergetool.adoc @@ -1,24 +1,24 @@ -mergetool..path:: +`mergetool..path`:: 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..cmd:: +`mergetool..cmd`:: Specify the command to invoke the specified merge tool. The 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; - '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 + `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 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. -mergetool..hideResolved:: +`mergetool..hideResolved`:: Allows the user to override the global `mergetool.hideResolved` value for a specific tool. See `mergetool.hideResolved` for the full description. -mergetool..trustExitCode:: +`mergetool..trustExitCode`:: For a custom merge command, specify whether the exit code of 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 @@ -26,7 +26,7 @@ mergetool..trustExitCode:: if the file has been updated; otherwise, the user is prompted to indicate the success of the merge. -mergetool.meld.hasOutput:: +`mergetool.meld.hasOutput`:: Older versions of `meld` do not support the `--output` option. Git will attempt to detect whether `meld` supports `--output` 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, and `false` avoids using `--output`. -mergetool.meld.useAutoMerge:: +`mergetool.meld.useAutoMerge`:: When the `--auto-merge` is given, meld will merge all non-conflicting parts automatically, highlight the conflicting parts, and wait for 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 default value. -mergetool..layout:: - Configure the split window layout for vimdiff's ``, which is any of `vimdiff`, +`mergetool..layout`:: + Configure the split window layout for vimdiff's __, which is any of `vimdiff`, `nvimdiff`, `gvimdiff`. Upon launching `git mergetool` with `--tool=` (or without `--tool` - if `merge.tool` is configured as ``), Git will consult + if `merge.tool` is configured as __), Git will consult `mergetool..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 - 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[] section. endif::[] @@ -61,39 +61,39 @@ ifndef::git-mergetool[] section in linkgit:git-mergetool[1]. endif::[] -mergetool.hideResolved:: +`mergetool.hideResolved`:: During a merge, Git will automatically resolve as many conflicts as - possible and write the 'MERGED' file containing conflict markers around - any conflicts that it cannot resolve; 'LOCAL' and 'REMOTE' normally - represent the versions of the file from before Git's conflict - resolution. This flag causes 'LOCAL' and 'REMOTE' to be overwritten so + possible and write the `$MERGED` file containing conflict markers around + any conflicts that it cannot resolve; `$LOCAL` and `$REMOTE` normally + are the versions of the file from before Git`s conflict + resolution. This flag causes `$LOCAL` and `$REMOTE` to be overwritten so that only the unresolved conflicts are presented to the merge tool. Can be configured per-tool via the `mergetool..hideResolved` configuration variable. Defaults to `false`. -mergetool.keepBackup:: +`mergetool.keepBackup`:: After performing a merge, the original file with conflict markers 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 `true` (i.e. keep the backup files). -mergetool.keepTemporaries:: +`mergetool.keepTemporaries`:: 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 variable is set to `true`, then these temporary files will be preserved; otherwise, they will be removed after the tool has exited. Defaults to `false`. -mergetool.writeToTemp:: - Git writes temporary 'BASE', 'LOCAL', and 'REMOTE' versions of +`mergetool.writeToTemp`:: + Git writes temporary `BASE`, `LOCAL`, and `REMOTE` versions of conflicting files in the worktree by default. Git will attempt to use a temporary directory for these files when set `true`. Defaults to `false`. -mergetool.prompt:: +`mergetool.prompt`:: Prompt before each invocation of the merge resolution program. -mergetool.guiDefault:: +`mergetool.guiDefault`:: Set `true` to use the `merge.guitool` by default (equivalent to specifying the `--gui` argument), or `auto` to select `merge.guitool` or `merge.tool` depending on the presence of a `DISPLAY` environment diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc index a66c53a5cd1e0a..ee83b6d9ba9a9b 100644 --- a/Documentation/git-checkout.adoc +++ b/Documentation/git-checkout.adoc @@ -7,54 +7,54 @@ git-checkout - Switch branches or restore working tree files SYNOPSIS -------- -[verse] -'git checkout' [-q] [-f] [-m] [] -'git checkout' [-q] [-f] [-m] --detach [] -'git checkout' [-q] [-f] [-m] [--detach] -'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] ] [] -'git checkout' [-f] [--] ... -'git checkout' [-f] --pathspec-from-file= [--pathspec-file-nul] -'git checkout' [-f|--ours|--theirs|-m|--conflict=