diff options
Diffstat (limited to 'Documentation')
93 files changed, 1346 insertions, 496 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 0ddd36879a..4cd95da6b1 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -526,12 +526,20 @@ Writing Documentation: modifying paragraphs or option/command explanations that contain options or commands: - Literal examples (e.g. use of command-line options, command names, and - configuration variables) are typeset in monospace, and if you can use - `backticks around word phrases`, do so. + Literal examples (e.g. use of command-line options, command names, + branch names, configuration and environment variables) must be + typeset in monospace (i.e. wrapped with backticks): `--pretty=oneline` `git rev-list` `remote.pushDefault` + `GIT_DIR` + `HEAD` + + An environment variable must be prefixed with "$" only when referring to its + value and not when referring to the variable itself, in this case there is + nothing to add except the backticks: + `GIT_DIR` is specified + `$GIT_DIR/hooks/pre-receive` Word phrases enclosed in `backtick characters` are rendered literally and will not be further expanded. The use of `backticks` to achieve the diff --git a/Documentation/Makefile b/Documentation/Makefile index 35c1385ef7..b43d66eae6 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -76,6 +76,7 @@ TECH_DOCS += technical/protocol-common TECH_DOCS += technical/racy-git TECH_DOCS += technical/send-pack-pipeline TECH_DOCS += technical/shallow +TECH_DOCS += technical/signature-format TECH_DOCS += technical/trivial-merge SP_ARTICLES += $(TECH_DOCS) SP_ARTICLES += technical/api-index diff --git a/Documentation/RelNotes/2.10.0.txt b/Documentation/RelNotes/2.10.0.txt new file mode 100644 index 0000000000..fe921ddd58 --- /dev/null +++ b/Documentation/RelNotes/2.10.0.txt @@ -0,0 +1,359 @@ +Git 2.10 Release Notes +====================== + +Backward compatibility notes +---------------------------- + +Updates since v2.9 +------------------ + +UI, Workflows & Features + + * "git pull --rebase --verify-signature" learned to warn the user + that "--verify-signature" is a no-op when rebasing. + + * An upstream project can make a recommendation to shallowly clone + some submodules in the .gitmodules file it ships. + + * "git worktree add" learned that '-' can be used as a short-hand for + "@{-1}", the previous branch. + + * Update the funcname definition to support css files. + + * The completion script (in contrib/) learned to complete "git + status" options. + + * Messages that are generated by auto gc during "git push" on the + receiving end are now passed back to the sending end in such a way + that they are shown with "remote: " prefix to avoid confusing the + users. + + * "git add -i/-p" learned to honor diff.compactionHeuristic + experimental knob, so that the user can work on the same hunk split + as "git diff" output. + + * "upload-pack" allows a custom "git pack-objects" replacement when + responding to "fetch/clone" via the uploadpack.packObjectsHook. + (merge 20b20a2 jk/upload-pack-hook later to maint). + + * Teach format-patch and mailsplit (hence "am") how a line that + happens to begin with "From " in the e-mail message is quoted with + ">", so that these lines can be restored to their original shape. + (merge d9925d1 ew/mboxrd-format-am later to maint). + + * "git repack" learned the "--keep-unreachable" option, which sends + loose unreachable objects to a pack instead of leaving them loose. + This helps heuristics based on the number of loose objects + (e.g. "gc --auto"). + (merge e26a8c4 jk/repack-keep-unreachable later to maint). + + * "log --graph --format=" learned that "%>|(N)" specifies the width + relative to the terminal's left edge, not relative to the area to + draw text that is to the right of the ancestry-graph section. It + also now accepts negative N that means the column limit is relative + to the right border. + + * A careless invocation of "git send-email directory/" after editing + 0001-change.patch with an editor often ends up sending both + 0001-change.patch and its backup file, 0001-change.patch~, causing + embarrassment and a minor confusion. Detect such an input and + offer to skip the backup files when sending the patches out. + (merge 531220b jc/send-email-skip-backup later to maint). + + * "git submodule update" that drives many "git clone" could + eventually hit flaky servers/network conditions on one of the + submodules; the command learned to retry the attempt. + + * The output coloring scheme learned two new attributes, italic and + strike, in addition to existing bold, reverse, etc. + + * "git log" learns log.showSignature configuration variable, and a + command line option "--no-show-signature" to countermand it. + (merge fce04c3 mj/log-show-signature-conf later to maint). + + * A couple of "git svn" updates. + + * More markings of messages for i18n, with updates to various tests + to pass GETTEXT_POISON tests. + + * "git archive" learned to handle files that are larger than 8GB and + commits far in the future than expressible by the traditional US-TAR + format. + (merge 5caeeb8 jk/big-and-future-archive-tar later to maint). + + * A new configuration variable core.sshCommand has been added to + specify what value for GIT_SSH_COMMAND to use per repository. + + +Performance, Internal Implementation, Development Support etc. + + * "git fast-import" learned the same performance trick to avoid + creating too small a packfile as "git fetch" and "git push" have, + using *.unpackLimit configuration. + + * When "git daemon" is run without --[init-]timeout specified, a + connection from a client that silently goes offline can hang around + for a long time, wasting resources. The socket-level KEEPALIVE has + been enabled to allow the OS to notice such failed connections. + + * "git upload-pack" command has been updated to use the parse-options + API. + + * The "git apply" standalone program is being libified; this is the + first step to move many state variables into a structure that can + be explicitly (re)initialized to make the machinery callable more + than once. + + * HTTP transport gained an option to produce more detailed debugging + trace. + (merge 73e57aa ep/http-curl-trace later to maint). + + * Instead of taking advantage of a struct string_list that is + allocated with all NULs happens to be STRING_LIST_INIT_NODUP kind, + initialize them explicitly as such, to document their behaviour + better. + (merge 2721ce2 jk/string-list-static-init later to maint). + + * HTTPd tests learned to show the server error log to help diagnosing + a failing tests. + (merge 44f243d nd/test-lib-httpd-show-error-log-in-verbose later to maint). + + * The ownership rule for the piece of memory that hold references to + be fetched in "git fetch" was screwy, which has been cleaned up. + + * "git bisect" makes an internal call to "git diff-tree" when + bisection finds the culprit, but this call did not initialize the + data structure to pass to the diff-tree API correctly. + + * Further preparatory clean-up for "worktree" feature continues. + (merge 0409e0b nd/worktree-cleanup-post-head-protection later to maint). + + * Formats of the various data (and how to validate them) where we use + GPG signature have been documented. + + * A new run-command API function pipe_command() is introduced to + sanely feed data to the standard input while capturing data from + the standard output and the standard error of an external process, + which is cumbersome to hand-roll correctly without deadlocking. + + The codepath to sign data in a prepared buffer with GPG has been + updated to use this API to read from the status-fd to check for + errors (instead of relying on GPG's exit status). + (merge efee955 jk/gpg-interface-cleanup later to maint). + + * Allow t/perf framework to use the features from the most recent + version of Git even when testing an older installed version. + + * The commands in the "log/diff" family have had an FILE* pointer in the + data structure they pass around for a long time, but some codepaths + used to always write to the standard output. As a preparatory step + to make "git format-patch" available to the internal callers, these + codepaths have been updated to consistently write into that FILE* + instead. + + * Conversion from unsigned char sha1[20] to struct object_id + continues. + + * Improve the look of the way "git fetch" reports what happened to + each ref that was fetched. + (merge bc437d1 nd/fetch-ref-summary later to maint). + + * The .c/.h sources are marked as such in our .gitattributes file so + that "git diff -W" and friends would work better. + (merge e82675a rs/help-c-source-with-gitattributes later to maint). + + * Code clean-up to avoid using a variable string that compilers may + feel untrustable as printf-style format given to write_file() + helper function. + + * "git p4" used a location outside $GIT_DIR/refs/ to place its + temporary branches, which has been moved to refs/git-p4-tmp/. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.9 +---------------- + +Unless otherwise noted, all the fixes since v2.8 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * The commands in `git log` family take %C(auto) in a custom format + string. This unconditionally turned the color on, ignoring + --no-color or with --color=auto when the output is not connected to + a tty; this was corrected to make the format truly behave as + "auto". + + * "git rev-list --count" whose walk-length is limited with "-n" + option did not work well with the counting optimized to look at the + bitmap index. + + * "git show -W" (extend hunks to cover the entire function, delimited + by lines that match the "funcname" pattern) used to show the entire + file when a change added an entire function at the end of the file, + which has been fixed. + + * The documentation set has been updated so that literal commands, + configuration variables and environment variables are consistently + typeset in fixed-width font and bold in manpages. + + * "git svn propset" subcommand that was added in 2.3 days is + documented now. + + * The documentation tries to consistently spell "GPG"; when + referring to the specific program name, "gpg" is used. + + * "git reflog" stopped upon seeing an entry that denotes a branch + creation event (aka "unborn"), which made it appear as if the + reflog was truncated. + + * The git-prompt scriptlet (in contrib/) was not friendly with those + who uses "set -u", which has been fixed. + + * compat/regex code did not cleanly compile. + + * A codepath that used alloca(3) to place an unbounded amount of data + on the stack has been updated to avoid doing so. + + * "git update-index --add --chmod=+x file" may be usable as an escape + hatch, but not a friendly thing to force for people who do need to + use it regularly. "git add --chmod=+x file" can be used instead. + + * Build improvements for gnome-keyring (in contrib/) + + * "git status" used to say "working directory" when it meant "working + tree". + + * Comments about misbehaving FreeBSD shells have been clarified with + the version number (9.x and before are broken, newer ones are OK). + + * "git cherry-pick A" worked on an unborn branch, but "git + cherry-pick A..B" didn't. + + * Fix an unintended regression in v2.9 that breaks "clone --depth" + that recurses down to submodules by forcing the submodules to also + be cloned shallowly, which many server instances that host upstream + of the submodules are not prepared for. + + * Fix unnecessarily waste in the idiomatic use of ': ${VAR=default}' + to set the default value, without enclosing it in double quotes. + + * Some platform-specific code had non-ANSI strict declarations of C + functions that do not take any parameters, which has been + corrected. + + * The internal code used to show local timezone offset is not + prepared to handle timestamps beyond year 2100, and gave a + bogus offset value to the caller. Use a more benign looking + +0000 instead and let "git log" going in such a case, instead + of aborting. + (merge bab7483 jk/tzoffset-fix later to maint). + + * One among four invocations of readlink(1) in our test suite has + been rewritten so that the test can run on systems without the + command (others are in valgrind test framework and t9802). + + * t/perf needs /usr/bin/time with GNU extension; the invocation of it + is updated to "gtime" on Darwin. + + * A bug, which caused "git p4" while running under verbose mode to + report paths that are omitted due to branch prefix incorrectly, has + been fixed; the command said "Ignoring file outside of prefix" for + paths that are _inside_. + + * The top level documentation "git help git" still pointed at the + documentation set hosted at now-defunct google-code repository. + Update it to point to https://git.github.io/htmldocs/git.html + instead. + + * A helper function that takes the contents of a commit object and + finds its subject line did not ignore leading blank lines, as is + commonly done by other codepaths. Make it ignore leading blank + lines to match. + (merge 054a5ae js/find-commit-subject-ignore-leading-blanks later to maint). + + * For a long time, we carried an in-code comment that said our + colored output would work only when we use fprintf/fputs on + Windows, which no longer is the case for the past few years. + (merge 3d0a833 js/color-on-windows-comment later to maint). + + * "gc.autoPackLimit" when set to 1 should not trigger a repacking + when there is only one pack, but the code counted poorly and did + so. + (merge 5f4e3bf ew/gc-auto-pack-limit-fix later to maint). + + * Add a test to specify the desired behaviour that currently is not + available in "git rebase -Xsubtree=...". + (merge 5f35900 dg/subtree-rebase-test later to maint). + + * More mark-up updates to typeset strings that are expected to + literally typed by the end user in fixed-width font. + (merge 661c3e9 mm/doc-tt later to maint). + + * "git commit --amend --allow-empty-message -S" for a commit without + any message body could have misidentified where the header of the + commit object ends. + (merge 3324dd8 js/sign-empty-commit-fix later to maint). + + * "git rebase -i --autostash" did not restore the auto-stashed change + when the operation was aborted. + (merge 33ba9c6 ps/rebase-i-auto-unstash-upon-abort later to maint). + + * Git does not know what the contents in the index should be for a + path added with "git add -N" yet, so "git grep --cached" should not + show hits (or show lack of hits, with -L) in such a path, but that + logic does not apply to "git grep", i.e. searching in the working + tree files. But we did so by mistake, which has been corrected. + (merge b8e47d1 nd/ita-cleanup later to maint). + + * "git blame -M" missed a single line that was moved within the file. + (merge 17a07e2 dk/blame-move-no-reason-for-1-line-context later to maint). + + * Fix recently introduced codepaths that are involved in parallel + submodule operations, which gave up on reading too early, and + could have wasted CPU while attempting to write under a corner + case condition. + (merge d751dd1 sb/submodule-parallel-fetch later to maint). + + * "git grep -i" has been taught to fold case in non-ascii locales + correctly. + (merge 695f95b nd/icase later to maint). + + * A test that unconditionally used "mktemp" learned that the command + is not necessarily available everywhere. + (merge c578a09 ak/lazy-prereq-mktemp later to maint). + + * There are certain house-keeping tasks that need to be performed at + the very beginning of any Git program, and programs that are not + built-in commands had to do them exactly the same way as "git" + potty does. It was easy to make mistakes in one-off standalone + programs (like test helpers). A common "main()" function that + calls cmd_main() of individual program has been introduced to + make it harder to make mistakes. + (merge de61ceb jk/common-main later to maint). + + * The test framework learned a new helper test_match_signal to + check an exit code from getting killed by an expected signal. + (merge 03c39b3 jk/test-match-signal later to maint). + + * General code clean-up around a helper function to write a + single-liner to a file. + (merge 7eb6e10 jk/write-file later to maint). + + * One part of "git am" had an oddball helper function that called + stuff from outside "his" as opposed to calling what we have "ours", + which was not gender-neutral and also inconsistent with the rest of + the system where outside stuff is usuall called "theirs" in + contrast to "ours". + (merge 715a51b js/am-call-theirs-theirs-in-fallback-3way later to maint). + + * Other minor clean-ups and documentation updates + (merge e51b0df pb/commit-editmsg-path later to maint). + (merge b333d0d jk/send-pack-stdio later to maint). + (merge fcf0fe9 lf/sideband-returns-void later to maint). + (merge c2691e2 ah/unpack-trees-advice-messages later to maint). + (merge 82f6178 nd/doc-new-command later to maint). + (merge fa90ab4 js/t3404-grammo-fix later to maint). + (merge c61b2af lf/recv-sideband-cleanup later to maint). diff --git a/Documentation/RelNotes/2.9.1.txt b/Documentation/RelNotes/2.9.1.txt new file mode 100644 index 0000000000..338394097e --- /dev/null +++ b/Documentation/RelNotes/2.9.1.txt @@ -0,0 +1,117 @@ +Git v2.9.1 Release Notes +======================== + +Fixes since v2.9 +---------------- + + * When "git daemon" is run without --[init-]timeout specified, a + connection from a client that silently goes offline can hang around + for a long time, wasting resources. The socket-level KEEPALIVE has + been enabled to allow the OS to notice such failed connections. + + * The commands in `git log` family take %C(auto) in a custom format + string. This unconditionally turned the color on, ignoring + --no-color or with --color=auto when the output is not connected to + a tty; this was corrected to make the format truly behave as + "auto". + + * "git rev-list --count" whose walk-length is limited with "-n" + option did not work well with the counting optimized to look at the + bitmap index. + + * "git show -W" (extend hunks to cover the entire function, delimited + by lines that match the "funcname" pattern) used to show the entire + file when a change added an entire function at the end of the file, + which has been fixed. + + * The documentation set has been updated so that literal commands, + configuration variables and environment variables are consistently + typeset in fixed-width font and bold in manpages. + + * "git svn propset" subcommand that was added in 2.3 days is + documented now. + + * The documentation tries to consistently spell "GPG"; when + referring to the specific program name, "gpg" is used. + + * "git reflog" stopped upon seeing an entry that denotes a branch + creation event (aka "unborn"), which made it appear as if the + reflog was truncated. + + * The git-prompt scriptlet (in contrib/) was not friendly with those + who uses "set -u", which has been fixed. + + * A codepath that used alloca(3) to place an unbounded amount of data + on the stack has been updated to avoid doing so. + + * "git update-index --add --chmod=+x file" may be usable as an escape + hatch, but not a friendly thing to force for people who do need to + use it regularly. "git add --chmod=+x file" can be used instead. + + * Build improvements for gnome-keyring (in contrib/) + + * "git status" used to say "working directory" when it meant "working + tree". + + * Comments about misbehaving FreeBSD shells have been clarified with + the version number (9.x and before are broken, newer ones are OK). + + * "git cherry-pick A" worked on an unborn branch, but "git + cherry-pick A..B" didn't. + + * "git add -i/-p" learned to honor diff.compactionHeuristic + experimental knob, so that the user can work on the same hunk split + as "git diff" output. + + * "log --graph --format=" learned that "%>|(N)" specifies the width + relative to the terminal's left edge, not relative to the area to + draw text that is to the right of the ancestry-graph section. It + also now accepts negative N that means the column limit is relative + to the right border. + + * The ownership rule for the piece of memory that hold references to + be fetched in "git fetch" was screwy, which has been cleaned up. + + * "git bisect" makes an internal call to "git diff-tree" when + bisection finds the culprit, but this call did not initialize the + data structure to pass to the diff-tree API correctly. + + * Formats of the various data (and how to validate them) where we use + GPG signature have been documented. + + * Fix an unintended regression in v2.9 that breaks "clone --depth" + that recurses down to submodules by forcing the submodules to also + be cloned shallowly, which many server instances that host upstream + of the submodules are not prepared for. + + * Fix unnecessarily waste in the idiomatic use of ': ${VAR=default}' + to set the default value, without enclosing it in double quotes. + + * Some platform-specific code had non-ANSI strict declarations of C + functions that do not take any parameters, which has been + corrected. + + * The internal code used to show local timezone offset is not + prepared to handle timestamps beyond year 2100, and gave a + bogus offset value to the caller. Use a more benign looking + +0000 instead and let "git log" going in such a case, instead + of aborting. + + * One among four invocations of readlink(1) in our test suite has + been rewritten so that the test can run on systems without the + command (others are in valgrind test framework and t9802). + + * t/perf needs /usr/bin/time with GNU extension; the invocation of it + is updated to "gtime" on Darwin. + + * A bug, which caused "git p4" while running under verbose mode to + report paths that are omitted due to branch prefix incorrectly, has + been fixed; the command said "Ignoring file outside of prefix" for + paths that are _inside_. + + * The top level documentation "git help git" still pointed at the + documentation set hosted at now-defunct google-code repository. + Update it to point to https://git.github.io/htmldocs/git.html + instead. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.9.2.txt b/Documentation/RelNotes/2.9.2.txt new file mode 100644 index 0000000000..2620003dcf --- /dev/null +++ b/Documentation/RelNotes/2.9.2.txt @@ -0,0 +1,13 @@ +Git v2.9.2 Release Notes +======================== + +Fixes since v2.9.1 +------------------ + + * A fix merged to v2.9.1 had a few tests that are not meant to be + run on platforms without 64-bit long, which caused unnecessary + test failures on them because we didn't detect the platform and + skip them. These tests are now skipped on platforms that they + are not applicable to. + +No other change is included in this update. diff --git a/Documentation/config.txt b/Documentation/config.txt index 2e1b2e486e..8b1aee4b3b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -140,7 +140,7 @@ boolean:: false;; Boolean false can be spelled as `no`, `off`, `false`, or `0`. + -When converting value to the canonical form using '--bool' type +When converting value to the canonical form using `--bool` type specifier; 'git config' will ensure that the output is "true" or "false" (spelled in lowercase). @@ -150,27 +150,34 @@ integer:: 1024", "by 1024x1024", etc. color:: - The value for a variables that takes a color is a list of - colors (at most two) and attributes (at most one), separated - by spaces. The colors accepted are `normal`, `black`, - `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and - `white`; the attributes are `bold`, `dim`, `ul`, `blink` and - `reverse`. The first color given is the foreground; the - second is the background. The position of the attribute, if - any, doesn't matter. Attributes may be turned off specifically - by prefixing them with `no` (e.g., `noreverse`, `noul`, etc). -+ -Colors (foreground and background) may also be given as numbers between -0 and 255; these use ANSI 256-color mode (but note that not all -terminals may support this). If your terminal supports it, you may also -specify 24-bit RGB values as hex, like `#ff0ab3`. -+ -The attributes are meant to be reset at the beginning of each item -in the colored output, so setting color.decorate.branch to `black` -will paint that branch name in a plain `black`, even if the previous -thing on the same output line (e.g. opening parenthesis before the -list of branch names in `log --decorate` output) is set to be -painted with `bold` or some other attribute. + The value for a variable that takes a color is a list of + colors (at most two, one for foreground and one for background) + and attributes (as many as you want), separated by spaces. ++ +The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`, +`blue`, `magenta`, `cyan` and `white`. The first color given is the +foreground; the second is the background. ++ +Colors may also be given as numbers between 0 and 255; these use ANSI +256-color mode (but note that not all terminals may support this). If +your terminal supports it, you may also specify 24-bit RGB values as +hex, like `#ff0ab3`. ++ +The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`, +`italic`, and `strike` (for crossed-out or "strikethrough" letters). +The position of any attributes with respect to the colors +(before, after, or in between), doesn't matter. Specific attributes may +be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`, +`no-ul`, etc). ++ +For git's pre-defined color slots, the attributes are meant to be reset +at the beginning of each item in the colored output. So setting +`color.decorate.branch` to `black` will paint that branch name in a +plain `black`, even if the previous thing on the same output line (e.g. +opening parenthesis before the list of branch names in `log --decorate` +output) is set to be painted with `bold` or some other attribute. +However, custom log formats may do more complicated and layered +coloring, and the negated forms may be useful there. pathname:: A variable that takes a pathname value can be given a @@ -405,13 +412,11 @@ file with mixed line endings would be reported by the `core.safecrlf` mechanism. core.autocrlf:: - Setting this variable to "true" is almost the same as setting - the `text` attribute to "auto" on all files except that text - files are not guaranteed to be normalized: files that contain - `CRLF` in the repository will not be touched. Use this - setting if you want to have `CRLF` line endings in your - working directory even though the repository does not have - normalized line endings. This variable can be set to 'input', + Setting this variable to "true" is the same as setting + the `text` attribute to "auto" on all files and core.eol to "crlf". + Set to true if you want to have `CRLF` line endings in your + working directory and the repository has LF line endings. + This variable can be set to 'input', in which case no output conversion is performed. core.symlinks:: @@ -434,7 +439,7 @@ core.gitProxy:: may be set multiple times and is matched in the given order; the first match wins. + -Can be overridden by the 'GIT_PROXY_COMMAND' environment variable +Can be overridden by the `GIT_PROXY_COMMAND` environment variable (which always applies universally, without the special "for" handling). + @@ -443,6 +448,13 @@ specify that no proxy be used for a given domain pattern. This is useful for excluding servers inside a firewall from proxy use, while defaulting to a common proxy for external domains. +core.sshCommand:: + If this variable is set, `git fetch` and `git push` will + use the specified command instead of `ssh` when they need to + connect to a remote system. The command is in the same form as + the `GIT_SSH_COMMAND` environment variable and is overridden + when the environment variable is set. + core.ignoreStat:: If true, Git will avoid using lstat() calls to detect if files have changed by setting the "assume-unchanged" bit for those tracked files @@ -478,10 +490,10 @@ false), while all other repositories are assumed to be bare (bare core.worktree:: Set the path to the root of the working tree. - If GIT_COMMON_DIR environment variable is set, core.worktree + If `GIT_COMMON_DIR` environment variable is set, core.worktree is ignored and not used for determining the root of working tree. - This can be overridden by the GIT_WORK_TREE environment - variable and the '--work-tree' command-line option. + This can be overridden by the `GIT_WORK_TREE` environment + variable and the `--work-tree` command-line option. The value can be an absolute path or relative to the path to the .git directory, which is either specified by --git-dir or GIT_DIR, or automatically discovered. @@ -545,7 +557,7 @@ core.compression:: -1 is the zlib default. 0 means no compression, and 1..9 are various speed/size tradeoffs, 9 being slowest. If set, this provides a default to other compression variables, - such as 'core.looseCompression' and 'pack.compression'. + such as `core.looseCompression` and `pack.compression`. core.looseCompression:: An integer -1..9, indicating the compression level for objects that @@ -619,9 +631,9 @@ core.excludesFile:: core.askPass:: Some commands (e.g. svn and http interfaces) that interactively ask for a password can be told to use an external program given - via the value of this variable. Can be overridden by the 'GIT_ASKPASS' + via the value of this variable. Can be overridden by the `GIT_ASKPASS` environment variable. If not set, fall back to the value of the - 'SSH_ASKPASS' environment variable or, failing that, a simple password + `SSH_ASKPASS` environment variable or, failing that, a simple password prompt. The external program shall be given a suitable prompt as command-line argument and write the password on its STDOUT. @@ -764,7 +776,7 @@ core.notesRef:: notes should be printed. + This setting defaults to "refs/notes/commits", and it can be overridden by -the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1]. +the `GIT_NOTES_REF` environment variable. See linkgit:git-notes[1]. core.sparseCheckout:: Enable "sparse checkout" feature. See section "Sparse checkout" in @@ -779,7 +791,7 @@ core.abbrev:: add.ignoreErrors:: add.ignore-errors (deprecated):: Tells 'git add' to continue adding files when some files cannot be - added due to indexing errors. Equivalent to the '--ignore-errors' + added due to indexing errors. Equivalent to the `--ignore-errors` option of linkgit:git-add[1]. `add.ignore-errors` is deprecated, as it does not follow the usual naming convention for configuration variables. @@ -800,14 +812,14 @@ it will be treated as a shell command. For example, defining "gitk --all --not ORIG_HEAD". Note that shell commands will be executed from the top-level directory of a repository, which may not necessarily be the current directory. -'GIT_PREFIX' is set as returned by running 'git rev-parse --show-prefix' +`GIT_PREFIX` is set as returned by running 'git rev-parse --show-prefix' from the original current directory. See linkgit:git-rev-parse[1]. am.keepcr:: If true, git-am will call git-mailsplit for patches in mbox format - with parameter '--keep-cr'. In this case git-mailsplit will + with parameter `--keep-cr`. In this case git-mailsplit will not remove `\r` from lines ending with `\r\n`. Can be overridden - by giving '--no-keep-cr' from the command line. + by giving `--no-keep-cr` from the command line. See linkgit:git-am[1], linkgit:git-mailsplit[1]. am.threeWay:: @@ -820,7 +832,7 @@ am.threeWay:: apply.ignoreWhitespace:: When set to 'change', tells 'git apply' to ignore changes in - whitespace, in the same way as the '--ignore-space-change' + whitespace, in the same way as the `--ignore-space-change` option. When set to one of: no, none, never, false tells 'git apply' to respect all whitespace differences. @@ -828,7 +840,7 @@ apply.ignoreWhitespace:: apply.whitespace:: Tells 'git apply' how to handle whitespaces, in the same way - as the '--whitespace' option. See linkgit:git-apply[1]. + as the `--whitespace` option. See linkgit:git-apply[1]. branch.autoSetupMerge:: Tells 'git branch' and 'git checkout' to set up new branches @@ -930,7 +942,7 @@ browser.<tool>.cmd:: browser.<tool>.path:: Override the path for the given tool that may be used to - browse HTML help (see '-w' option in linkgit:git-help[1]) or a + browse HTML help (see `-w` option in linkgit:git-help[1]) or a working repository in gitweb (see linkgit:git-instaweb[1]). clean.requireForce:: @@ -1189,6 +1201,15 @@ difftool.<tool>.cmd:: difftool.prompt:: Prompt before each invocation of the diff tool. +fastimport.unpackLimit:: + If the number of objects imported by linkgit:git-fast-import[1] + is below this limit, then the objects will be unpacked into + loose object files. However if the number of imported objects + equals or exceeds this limit then the pack will be stored as a + pack. Storing the pack from a fast-import can make the import + operation complete faster, especially on slow filesystems. If + not set, the value of `transfer.unpackLimit` is used instead. + fetch.recurseSubmodules:: This option can be either set to a boolean value or to 'on-demand'. Setting it to a boolean changes the behavior of fetch and pull to @@ -1220,6 +1241,11 @@ fetch.prune:: If true, fetch will automatically behave as if the `--prune` option was given on the command line. See also `remote.<name>.prune`. +fetch.output:: + Control how ref update status is printed. Valid values are + `full` and `compact`. Default value is `full`. See section + OUTPUT in linkgit:git-fetch[1] for detail. + format.attach:: Enable multipart/mixed attachments as the default for 'format-patch'. The value can also be a double quoted string @@ -1420,24 +1446,24 @@ gitcvs.logFile:: gitcvs.usecrlfattr:: If true, the server will look up the end-of-line conversion - attributes for files to determine the '-k' modes to use. If + attributes for files to determine the `-k` modes to use. If the attributes force Git to treat a file as text, - the '-k' mode will be left blank so CVS clients will + the `-k` mode will be left blank so CVS clients will treat it as text. If they suppress text conversion, the file will be set with '-kb' mode, which suppresses any newline munging the client might otherwise do. If the attributes do not allow - the file type to be determined, then 'gitcvs.allBinary' is + the file type to be determined, then `gitcvs.allBinary` is used. See linkgit:gitattributes[5]. gitcvs.allBinary:: - This is used if 'gitcvs.usecrlfattr' does not resolve + This is used if `gitcvs.usecrlfattr` does not resolve the correct '-kb' mode to use. If true, all unresolved files are sent to the client in mode '-kb'. This causes the client to treat them as binary files, which suppresses any newline munging it otherwise might do. Alternatively, if it is set to "guess", then the contents of the file are examined to decide if - it is binary, similar to 'core.autocrlf'. + it is binary, similar to `core.autocrlf`. gitcvs.dbName:: Database used by git-cvsserver to cache revision information @@ -1456,7 +1482,7 @@ gitcvs.dbDriver:: See linkgit:git-cvsserver[1]. gitcvs.dbUser, gitcvs.dbPass:: - Database user and password. Only useful if setting 'gitcvs.dbDriver', + Database user and password. Only useful if setting `gitcvs.dbDriver`, since SQLite has no concept of database users and/or passwords. 'gitcvs.dbUser' supports variable substitution (see linkgit:git-cvsserver[1] for details). @@ -1468,8 +1494,8 @@ gitcvs.dbTableNamePrefix:: linkgit:git-cvsserver[1] for details). Any non-alphabetic characters will be replaced with underscores. -All gitcvs variables except for 'gitcvs.usecrlfattr' and -'gitcvs.allBinary' can also be specified as +All gitcvs variables except for `gitcvs.usecrlfattr` and +`gitcvs.allBinary` can also be specified as 'gitcvs.<access_method>.<varname>' (where 'access_method' is one of "ext" and "pserver") to make them apply only for the given access method. @@ -1492,17 +1518,17 @@ gitweb.snapshot:: See linkgit:gitweb.conf[5] for description. grep.lineNumber:: - If set to true, enable '-n' option by default. + If set to true, enable `-n` option by default. grep.patternType:: Set the default matching behavior. Using a value of 'basic', 'extended', - 'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp', - '--fixed-strings', or '--perl-regexp' option accordingly, while the + 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`, + `--fixed-strings`, or `--perl-regexp` option accordingly, while the value 'default' will return to the default matching behavior. grep.extendedRegexp:: - If set to true, enable '--extended-regexp' option by default. This - option is ignored when the 'grep.patternType' option is set to a value + If set to true, enable `--extended-regexp` option by default. This + option is ignored when the `grep.patternType` option is set to a value other than 'default'. grep.threads:: @@ -1587,7 +1613,7 @@ guitool.<name>.cmd:: of the linkgit:git-gui[1] `Tools` menu is invoked. This option is mandatory for every tool. The command is executed from the root of the working directory, and in the environment it receives the name of - the tool as 'GIT_GUITOOL', the name of the currently selected file as + the tool as `GIT_GUITOOL`, the name of the currently selected file as 'FILENAME', and the name of the current branch as 'CUR_BRANCH' (if the head is detached, 'CUR_BRANCH' is empty). @@ -1608,7 +1634,7 @@ guitool.<name>.confirm:: guitool.<name>.argPrompt:: Request a string argument from the user, and pass it to the tool - through the 'ARGS' environment variable. Since requesting an + through the `ARGS` environment variable. Since requesting an argument implies confirmation, the 'confirm' option has no effect if this is enabled. If the option is set to 'true', 'yes', or '1', the dialog uses a built-in generic prompt; otherwise the exact @@ -1616,7 +1642,7 @@ guitool.<name>.argPrompt:: guitool.<name>.revPrompt:: Request a single valid revision from the user, and set the - 'REVISION' environment variable. In other aspects this option + `REVISION` environment variable. In other aspects this option is similar to 'argPrompt', and can be used together with it. guitool.<name>.revUnmerged:: @@ -1672,7 +1698,7 @@ http.proxyAuthMethod:: only takes effect if the configured proxy string contains a user name part (i.e. is of the form 'user@host' or 'user@host:port'). This can be overridden on a per-remote basis; see `remote.<name>.proxyAuthMethod`. - Both can be overridden by the 'GIT_HTTP_PROXY_AUTHMETHOD' environment + Both can be overridden by the `GIT_HTTP_PROXY_AUTHMETHOD` environment variable. Possible values are: + -- @@ -1731,9 +1757,9 @@ http.sslVersion:: - tlsv1.2 + -Can be overridden by the 'GIT_SSL_VERSION' environment variable. +Can be overridden by the `GIT_SSL_VERSION` environment variable. To force git to use libcurl's default ssl version and ignore any -explicit http.sslversion option, set 'GIT_SSL_VERSION' to the +explicit http.sslversion option, set `GIT_SSL_VERSION` to the empty string. http.sslCipherList:: @@ -1744,41 +1770,41 @@ http.sslCipherList:: option; see the libcurl documentation for more details on the format of this list. + -Can be overridden by the 'GIT_SSL_CIPHER_LIST' environment variable. +Can be overridden by the `GIT_SSL_CIPHER_LIST` environment variable. To force git to use libcurl's default cipher list and ignore any -explicit http.sslCipherList option, set 'GIT_SSL_CIPHER_LIST' to the +explicit http.sslCipherList option, set `GIT_SSL_CIPHER_LIST` to the empty string. http.sslVerify:: Whether to verify the SSL certificate when fetching or pushing - over HTTPS. Can be overridden by the 'GIT_SSL_NO_VERIFY' environment + over HTTPS. Can be overridden by the `GIT_SSL_NO_VERIFY` environment variable. http.sslCert:: File containing the SSL certificate when fetching or pushing - over HTTPS. Can be overridden by the 'GIT_SSL_CERT' environment + over HTTPS. Can be overridden by the `GIT_SSL_CERT` environment variable. http.sslKey:: File containing the SSL private key when fetching or pushing - over HTTPS. Can be overridden by the 'GIT_SSL_KEY' environment + over HTTPS. Can be overridden by the `GIT_SSL_KEY` environment variable. http.sslCertPasswordProtected:: Enable Git's password prompt for the SSL certificate. Otherwise OpenSSL will prompt the user, possibly many times, if the certificate or private key is encrypted. Can be overridden by the - 'GIT_SSL_CERT_PASSWORD_PROTECTED' environment variable. + `GIT_SSL_CERT_PASSWORD_PROTECTED` environment variable. http.sslCAInfo:: File containing the certificates to verify the peer with when fetching or pushing over HTTPS. Can be overridden by the - 'GIT_SSL_CAINFO' environment variable. + `GIT_SSL_CAINFO` environment variable. http.sslCAPath:: Path containing files with the CA certificates to verify the peer with when fetching or pushing over HTTPS. Can be overridden - by the 'GIT_SSL_CAPATH' environment variable. + by the `GIT_SSL_CAPATH` environment variable. http.pinnedpubkey:: Public key of the https service. It may either be the filename of @@ -1798,7 +1824,7 @@ http.sslTry:: http.maxRequests:: How many HTTP requests to launch in parallel. Can be overridden - by the 'GIT_HTTP_MAX_REQUESTS' environment variable. Default is 5. + by the `GIT_HTTP_MAX_REQUESTS` environment variable. Default is 5. http.minSessions:: The number of curl sessions (counted across slots) to be kept across @@ -1817,13 +1843,13 @@ http.postBuffer:: http.lowSpeedLimit, http.lowSpeedTime:: If the HTTP transfer speed is less than 'http.lowSpeedLimit' for longer than 'http.lowSpeedTime' seconds, the transfer is aborted. - Can be overridden by the 'GIT_HTTP_LOW_SPEED_LIMIT' and - 'GIT_HTTP_LOW_SPEED_TIME' environment variables. + Can be overridden by the `GIT_HTTP_LOW_SPEED_LIMIT` and + `GIT_HTTP_LOW_SPEED_TIME` environment variables. http.noEPSV:: A boolean which disables using of EPSV ftp command by curl. This can helpful with some "poor" ftp servers which don't - support EPSV mode. Can be overridden by the 'GIT_CURL_FTP_NO_EPSV' + support EPSV mode. Can be overridden by the `GIT_CURL_FTP_NO_EPSV` environment variable. Default is false (curl will use EPSV). http.userAgent:: @@ -1833,7 +1859,7 @@ http.userAgent:: such as Mozilla/4.0. This may be necessary, for instance, if connecting through a firewall that restricts HTTP connections to a set of common USER_AGENT strings (but not including those like git/1.7.1). - Can be overridden by the 'GIT_HTTP_USER_AGENT' environment variable. + Can be overridden by the `GIT_HTTP_USER_AGENT` environment variable. http.<url>.*:: Any of the http.* options above can be applied selectively to some URLs. @@ -1958,7 +1984,7 @@ log.decorate:: specified, the full ref name (including prefix) will be printed. If 'auto' is specified, then if the output is going to a terminal, the ref names are shown as if 'short' were given, otherwise no ref - names are shown. This is the same as the '--decorate' option + names are shown. This is the same as the `--decorate` option of the `git log`. log.follow:: @@ -2341,16 +2367,16 @@ new default). -- push.followTags:: - If set to true enable '--follow-tags' option by default. You + If set to true enable `--follow-tags` option by default. You may override this configuration at time of push by specifying - '--no-follow-tags'. + `--no-follow-tags`. push.gpgSign:: May be set to a boolean value, or the string 'if-asked'. A true - value causes all pushes to be GPG signed, as if '--signed' is + value causes all pushes to be GPG signed, as if `--signed` is passed to linkgit:git-push[1]. The string 'if-asked' causes pushes to be signed if the server supports it, as if - '--signed=if-asked' is passed to 'git push'. A false value may + `--signed=if-asked` is passed to 'git push'. A false value may override a value from a lower-priority config file. An explicit command-line flag always overrides this config option. @@ -2373,7 +2399,7 @@ rebase.stat:: rebase. False by default. rebase.autoSquash:: - If set to true enable '--autosquash' option by default. + If set to true enable `--autosquash` option by default. rebase.autoStash:: When set to true, automatically create a temporary stash @@ -2630,7 +2656,7 @@ sendemail.identity:: A configuration identity. When given, causes values in the 'sendemail.<identity>' subsection to take precedence over values in the 'sendemail' section. The default identity is - the value of 'sendemail.identity'. + the value of `sendemail.identity`. sendemail.smtpEncryption:: See linkgit:git-send-email[1] for description. Note that this @@ -2647,7 +2673,7 @@ sendemail.<identity>.*:: Identity-specific versions of the 'sendemail.*' parameters found below, taking precedence over those when the this identity is selected, through command-line or - 'sendemail.identity'. + `sendemail.identity`. sendemail.aliasesFile:: sendemail.aliasFileType:: @@ -2677,7 +2703,7 @@ sendemail.xmailer:: See linkgit:git-send-email[1] for description. sendemail.signedoffcc (deprecated):: - Deprecated alias for 'sendemail.signedoffbycc'. + Deprecated alias for `sendemail.signedoffbycc`. showbranch.default:: The default set of branches for linkgit:git-show-branch[1]. @@ -2883,6 +2909,21 @@ uploadpack.keepAlive:: `uploadpack.keepAlive` seconds. Setting this option to 0 disables keepalive packets entirely. The default is 5 seconds. +uploadpack.packObjectsHook:: + If this option is set, when `upload-pack` would run + `git pack-objects` to create a packfile for a client, it will + run this shell command instead. The `pack-objects` command and + arguments it _would_ have run (including the `git pack-objects` + at the beginning) are appended to the shell command. The stdin + and stdout of the hook are treated as if `pack-objects` itself + was run. I.e., `upload-pack` will feed input intended for + `pack-objects` to the hook, and expects a completed packfile on + stdout. ++ +Note that this configuration variable is ignored if it is seen in the +repository-level config (this is a safety measure against fetching from +untrusted repositories). + url.<base>.insteadOf:: Any URL that starts with this value will be rewritten to start, instead, with <base>. In cases where some site serves a @@ -2909,17 +2950,17 @@ url.<base>.pushInsteadOf:: user.email:: Your email address to be recorded in any newly created commits. - Can be overridden by the 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_EMAIL', and - 'EMAIL' environment variables. See linkgit:git-commit-tree[1]. + Can be overridden by the `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_EMAIL`, and + `EMAIL` environment variables. See linkgit:git-commit-tree[1]. user.name:: Your full name to be recorded in any newly created commits. - Can be overridden by the 'GIT_AUTHOR_NAME' and 'GIT_COMMITTER_NAME' + Can be overridden by the `GIT_AUTHOR_NAME` and `GIT_COMMITTER_NAME` environment variables. See linkgit:git-commit-tree[1]. user.useConfigOnly:: - Instruct Git to avoid trying to guess defaults for 'user.email' - and 'user.name', and instead retrieve the values only from the + Instruct Git to avoid trying to guess defaults for `user.email` + and `user.name`, and instead retrieve the values only from the configuration. For example, if you have multiple email addresses and would like to use a different one for each repository, then with this configuration option set to `true` in the global config diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt index ccd1fc8122..35e8da2010 100644 --- a/Documentation/date-formats.txt +++ b/Documentation/date-formats.txt @@ -1,7 +1,7 @@ DATE FORMATS ------------ -The GIT_AUTHOR_DATE, GIT_COMMITTER_DATE environment variables +The `GIT_AUTHOR_DATE`, `GIT_COMMITTER_DATE` environment variables ifdef::git-commit[] and the `--date` option endif::git-commit[] diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index d78cfc5a37..d5a5b17d50 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -75,7 +75,7 @@ diff.ignoreSubmodules:: commands such as 'git diff-files'. 'git checkout' also honors this setting when reporting uncommitted changes. Setting it to 'all' disables the submodule summary normally shown by 'git commit' - and 'git status' when 'status.submoduleSummary' is set unless it is + and 'git status' when `status.submoduleSummary` is set unless it is overridden by using the --ignore-submodules command-line option. The 'git submodule' commands are not affected by this setting. @@ -105,7 +105,7 @@ diff.orderFile:: diff.renameLimit:: The number of files to consider when performing the copy/rename - detection; equivalent to the 'git diff' option '-l'. + detection; equivalent to the 'git diff' option `-l`. diff.renames:: Whether and how Git detects renames. If set to "false", diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 85b08909ce..cf5262622f 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -46,11 +46,11 @@ That is, from the left to the right: . sha1 for "dst"; 0\{40\} if creation, unmerged or "look at work tree". . a space. . status, followed by optional "score" number. -. a tab or a NUL when '-z' option is used. +. a tab or a NUL when `-z` option is used. . path for "src" -. a tab or a NUL when '-z' option is used; only exists for C or R. +. a tab or a NUL when `-z` option is used; only exists for C or R. . path for "dst"; only exists for C or R. -. an LF or a NUL when '-z' option is used, to terminate the record. +. an LF or a NUL when `-z` option is used, to terminate the record. Possible status letters are: @@ -86,7 +86,7 @@ diff format for merges ---------------------- "git-diff-tree", "git-diff-files" and "git-diff --raw" -can take '-c' or '--cc' option +can take `-c` or `--cc` option to generate diff output also for merge commits. The output differs from the format described above in the following way: diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index bcf54da82a..d2a7ff56e8 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -2,11 +2,11 @@ Generating patches with -p -------------------------- When "git-diff-index", "git-diff-tree", or "git-diff-files" are run -with a '-p' option, "git diff" without the '--raw' option, or +with a `-p` option, "git diff" without the `--raw` option, or "git log" with the "-p" option, they do not produce the output described above; instead they produce a patch file. You can customize the creation of such patches via the -GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables. +`GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables. What the -p option produces is slightly different from the traditional diff format: @@ -114,11 +114,11 @@ index fabadb8,cc95eb0..4866510 ------------ 1. It is preceded with a "git diff" header, that looks like - this (when '-c' option is used): + this (when `-c` option is used): diff --combined file + -or like this (when '--cc' option is used): +or like this (when `--cc` option is used): diff --cc file diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index d9ae681d8f..705a873942 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -419,6 +419,9 @@ ifndef::git-format-patch[] paths are selected if there is any file that matches other criteria in the comparison; if there is no file that matches other criteria, nothing is selected. ++ +Also, these upper-case letters can be downcased to exclude. E.g. +`--diff-filter=ad` excludes added and deleted paths. -S<string>:: Look for differences that change the number of occurrences of diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 036edfb099..9eab1f5fa4 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -52,7 +52,7 @@ ifndef::git-pull[] -p:: --prune:: - After fetching, remove any remote-tracking references that no + Before fetching, remove any remote-tracking references that no longer exist on the remote. Tags are not subject to pruning if they are fetched only because of the default tag auto-following or due to a --tags option. However, if tags @@ -88,7 +88,7 @@ ifndef::git-pull[] to whatever else would otherwise be fetched. Using this option alone does not subject tags to pruning, even if --prune is used (though tags may be pruned anyway if they are also the - destination of an explicit refspec; see '--prune'). + destination of an explicit refspec; see `--prune`). --recurse-submodules[=yes|on-demand|no]:: This option controls if and under what conditions new commits of @@ -110,7 +110,7 @@ ifndef::git-pull[] --no-recurse-submodules:: Disable recursive fetching of submodules (this has the same effect as - using the '--recurse-submodules=no' option). + using the `--recurse-submodules=no` option). --submodule-prefix=<path>:: Prepend <path> to paths printed in informative messages @@ -137,7 +137,7 @@ endif::git-pull[] --upload-pack <upload-pack>:: When given, and the repository to fetch from is handled - by 'git fetch-pack', '--exec=<upload-pack>' is passed to + by 'git fetch-pack', `--exec=<upload-pack>` is passed to the command to specify non-default path for the command run on the other end. diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 13cdd7f3b6..12879e4029 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -116,7 +116,8 @@ default. You can use `--no-utf8` to override this. By default the command will try to detect the patch format automatically. This option allows the user to bypass the automatic detection and specify the patch format that the patch(es) should be - interpreted as. Valid formats are mbox, stgit, stgit-series and hg. + interpreted as. Valid formats are mbox, mboxrd, + stgit, stgit-series and hg. -i:: --interactive:: @@ -198,12 +199,12 @@ When initially invoking `git am`, you give it the names of the mailboxes to process. Upon seeing the first patch that does not apply, it aborts in the middle. You can recover from this in one of two ways: -. skip the current patch by re-running the command with the '--skip' +. skip the current patch by re-running the command with the `--skip` option. . hand resolve the conflict in the working directory, and update the index file to bring it into a state that the patch should - have produced. Then run the command with the '--continue' option. + have produced. Then run the command with the `--continue` option. The command refuses to process new mailboxes until the current operation is finished, so if you decide to start over from scratch, diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index c06efbd42a..e015f5b3cc 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -366,7 +366,7 @@ skip" to do the same thing. (In fact the special exit code 125 makes Or if you want more control, you can inspect the current state using for example "git bisect visualize". It will launch gitk (or "git log" -if the DISPLAY environment variable is not set) to help you find a +if the `DISPLAY` environment variable is not set) to help you find a better bisection point. Either way, if you have a string of untestable commits, it might diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 7e79aaedeb..2bb9a577a2 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -205,7 +205,7 @@ $ git bisect visualize `view` may also be used as a synonym for `visualize`. -If the 'DISPLAY' environment variable is not set, 'git log' is used +If the `DISPLAY` environment variable is not set, 'git log' is used instead. You can also give command-line options such as `-p` and `--stat`. @@ -358,7 +358,7 @@ OPTIONS --no-checkout:: + Do not checkout the new working tree at each iteration of the bisection -process. Instead just update a special reference named 'BISECT_HEAD' to make +process. Instead just update a special reference named `BISECT_HEAD` to make it point to the commit that should be tested. + This option may be useful when the test you would perform in each step diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 4a7037f1c8..1fe73448f3 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -39,10 +39,10 @@ named commit). With `--merged`, only branches merged into the named commit (i.e. the branches whose tip commits are reachable from the named commit) will be listed. With `--no-merged` only branches not merged into the named commit will be listed. If the <commit> argument is missing it -defaults to 'HEAD' (i.e. the tip of the current branch). +defaults to `HEAD` (i.e. the tip of the current branch). The command's second form creates a new branch head named <branchname> -which points to the current 'HEAD', or <start-point> if given. +which points to the current `HEAD`, or <start-point> if given. Note that this will create the new branch, but it will not switch the working tree to it; use "git checkout <newbranch>" to switch to the @@ -172,7 +172,7 @@ This option is only applicable in non-verbose mode. + This behavior is the default when the start point is a remote-tracking branch. Set the branch.autoSetupMerge configuration variable to `false` if you -want `git checkout` and `git branch` to always behave as if '--no-track' +want `git checkout` and `git branch` to always behave as if `--no-track` were given. Set it to `always` if you want this behavior when the start-point is either a local or remote-tracking branch. diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index eb3d6945a9..18d03d8e8b 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -15,8 +15,8 @@ SYNOPSIS DESCRIPTION ----------- In its first form, the command provides the content or the type of an object in -the repository. The type is required unless '-t' or '-p' is used to find the -object type, or '-s' is used to find the object size, or '--textconv' is used +the repository. The type is required unless `-t` or `-p` is used to find the +object type, or `-s` is used to find the object size, or `--textconv` is used (which implies type "blob"). In the second form, a list of objects (separated by linefeeds) is provided on @@ -144,13 +144,13 @@ respectively print: OUTPUT ------ -If '-t' is specified, one of the <type>. +If `-t` is specified, one of the <type>. -If '-s' is specified, the size of the <object> in bytes. +If `-s` is specified, the size of the <object> in bytes. -If '-e' is specified, no output. +If `-e` is specified, no output. -If '-p' is specified, the contents of <object> are pretty-printed. +If `-p` is specified, the contents of <object> are pretty-printed. If <type> is specified, the raw (though uncompressed) contents of the <object> will be returned. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 5e5273e073..7a2201b051 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -157,7 +157,7 @@ of it"). When creating a new branch, set up "upstream" configuration. See "--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 the refspec configured for the corresponding remote, and then stripping the initial part up to the "*". @@ -165,7 +165,7 @@ This would tell us to use "hack" as the local branch when branching off of "origin/hack" (or "remotes/origin/hack", or even "refs/remotes/origin/hack"). If the 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 '-b' in such a case. +explicitly give a name with `-b` in such a case. --no-track:: Do not set up "upstream" configuration, even if the diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index c104a594af..d35d771fc8 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -47,7 +47,7 @@ OPTIONS For a more complete list of ways to spell commits, see linkgit:gitrevisions[7]. Sets of commits can be passed but no traversal is done by - default, as if the '--no-walk' option was specified, see + default, as if the `--no-walk` option was specified, see linkgit:git-rev-list[1]. Note that specifying a range will feed all <commit>... arguments to a single revision walk (see a later example that uses 'maint master..next'). diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 51a7e26a8e..03056dad0d 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -16,7 +16,7 @@ DESCRIPTION Cleans the working tree by recursively removing files that are not under version control, starting from the current directory. -Normally, only files unknown to Git are removed, but if the '-x' +Normally, only files unknown to Git are removed, but if the `-x` option is specified, ignored files are also removed. This can, for example, be useful to remove all build products. diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 1b15cd7b16..ec41d3d698 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -191,9 +191,8 @@ objects from the source repository into a pack in the cloned repository. Create a 'shallow' clone with a history truncated to the specified number of commits. Implies `--single-branch` unless `--no-single-branch` is given to fetch the histories near the - tips of all branches. This implies `--shallow-submodules`. If - you want to have a shallow superproject clone, but full submodules, - also pass `--no-shallow-submodules`. + tips of all branches. If you want to clone submodules shallowly, + also pass `--shallow-submodules`. --[no-]single-branch:: Clone only the history leading to the tip of a single branch, diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index cb69faab68..002dae625e 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -44,7 +44,7 @@ OPTIONS An existing tree object -p <parent>:: - Each '-p' indicates the id of a parent commit object. + Each `-p` indicates the id of a parent commit object. -m <message>:: A paragraph in the commit log message. This can be given more than diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index d474226eb7..b0a294d3b5 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -75,7 +75,7 @@ OPTIONS -c <commit>:: --reedit-message=<commit>:: - Like '-C', but with '-c' the editor is invoked, so that + Like '-C', but with `-c` the editor is invoked, so that the user can further edit the commit message. --fixup=<commit>:: @@ -201,7 +201,7 @@ default:: Otherwise `whitespace`. -- + -The default can be changed by the 'commit.cleanup' configuration +The default can be changed by the `commit.cleanup` configuration variable (see linkgit:git-config[1]). -e:: @@ -260,7 +260,7 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) staged for other paths. This is the default mode of operation of 'git commit' if any paths are given on the command line, in which case this option can be omitted. - If this option is specified together with '--amend', then + If this option is specified together with `--amend`, then no paths need to be specified, which can be used to amend the last commit without committing changes that have already been staged. @@ -450,8 +450,8 @@ include::i18n.txt[] ENVIRONMENT AND CONFIGURATION VARIABLES --------------------------------------- The editor used to edit the commit log message will be chosen from the -GIT_EDITOR environment variable, the core.editor configuration variable, the -VISUAL environment variable, or the EDITOR environment variable (in that +`GIT_EDITOR` environment variable, the core.editor configuration variable, the +`VISUAL` environment variable, or the `EDITOR` environment variable (in that order). See linkgit:git-var[1] for details. HOOKS diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 6843114fc0..f163113a6f 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -31,29 +31,29 @@ You can query/set/replace/unset options with this command. The name is actually the section and the key separated by a dot, and the value will be escaped. -Multiple lines can be added to an option by using the '--add' option. +Multiple lines can be added to an option by using the `--add` option. If you want to update or unset an option which can occur on multiple lines, a POSIX regexp `value_regex` needs to be given. Only the existing values that match the regexp are updated or unset. If you want to handle the lines that do *not* match the regex, just prepend a single exclamation mark in front (see also <<EXAMPLES>>). -The type specifier can be either '--int' or '--bool', to make +The type specifier can be either `--int` or `--bool`, to make 'git config' ensure that the variable(s) are of the given type and convert the value to the canonical form (simple decimal number for int, -a "true" or "false" string for bool), or '--path', which does some -path expansion (see '--path' below). If no type specifier is passed, no +a "true" or "false" string for bool), or `--path`, which does some +path expansion (see `--path` below). If no type specifier is passed, no checks or transformations are performed on the value. When reading, the values are read from the system, global and repository local configuration files by default, and options -'--system', '--global', '--local' and '--file <filename>' can be +`--system`, `--global`, `--local` and `--file <filename>` can be used to tell the command to read from only that location (see <<FILES>>). When writing, the new value is written to the repository local -configuration file by default, and options '--system', '--global', -'--file <filename>' can be used to tell the command to write to -that location (you can say '--local' but that is the default). +configuration file by default, and options `--system`, `--global`, +`--file <filename>` can be used to tell the command to write to +that location (you can say `--local` but that is the default). This command will fail with non-zero status upon error. Some exit codes are: @@ -138,7 +138,7 @@ See also <<FILES>>. Use the given config file instead of the one specified by GIT_CONFIG. --blob blob:: - Similar to '--file' but use the given blob instead of a file. E.g. + Similar to `--file` but use the given blob instead of a file. E.g. you can use 'master:.gitmodules' to read values from the file '.gitmodules' in the master branch. See "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7] for a more complete list of @@ -220,7 +220,7 @@ See also <<FILES>>. -e:: --edit:: Opens an editor to modify the specified config file; either - '--system', '--global', or repository (default). + `--system`, `--global`, or repository (default). --[no-]includes:: Respect `include.*` directives in config files when looking up @@ -232,7 +232,7 @@ See also <<FILES>>. FILES ----- -If not set explicitly with '--file', there are four files where +If not set explicitly with `--file`, there are four files where 'git config' will search for configuration options: $(prefix)/etc/gitconfig:: @@ -264,12 +264,12 @@ precedence over values read earlier. When multiple values are taken then all values of a key from all files will be used. All writing options will per default write to the repository specific -configuration file. Note that this also affects options like '--replace-all' -and '--unset'. *'git config' will only ever change one file at a time*. +configuration file. Note that this also affects options like `--replace-all` +and `--unset`. *'git config' will only ever change one file at a time*. You can override these rules either by command-line options or by environment -variables. The '--global' and the '--system' options will limit the file used -to the global or system-wide file respectively. The GIT_CONFIG environment +variables. The `--global` and the `--system` options will limit the file used +to the global or system-wide file respectively. The `GIT_CONFIG` environment variable has a similar effect, but you can specify any filename you want. diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index e3c8f276b1..25fb963f4b 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -44,7 +44,7 @@ OPTIONS FILES ----- -If not set explicitly with '--file', there are two files where +If not set explicitly with `--file`, there are two files where git-credential-store will search for credentials in order of precedence: ~/.git-credentials:: diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index 00a0679a28..41207a24b0 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -74,10 +74,10 @@ OPTIONS akin to the way 'git clone' uses 'origin' by default. -o <branch-for-HEAD>:: - When no remote is specified (via -r) the 'HEAD' branch + When no remote is specified (via -r) the `HEAD` branch from CVS is imported to the 'origin' branch within the Git - repository, as 'HEAD' already has a special meaning for Git. - When a remote is specified the 'HEAD' branch is named + repository, as `HEAD` already has a special meaning for Git. + When a remote is specified the `HEAD` branch is named remotes/<remote>/master mirroring 'git clone' behaviour. Use this option if you want to import into a different branch. @@ -103,7 +103,7 @@ the old cvs2git tool. -p <options-for-cvsps>:: Additional options for cvsps. - The options '-u' and '-A' are implicit and should not be used here. + The options `-u` and '-A' are implicit and should not be used here. + If you need to pass multiple options, separate them with a comma. @@ -122,7 +122,7 @@ If you need to pass multiple options, separate them with a comma. -M <regex>:: Attempt to detect merges based on the commit message with a custom - regex. It can be used with '-m' to enable the default regexes + regex. It can be used with `-m` to enable the default regexes as well. You must escape forward slashes. + The regex must capture the source branch name in $1. @@ -186,7 +186,7 @@ messages, bug-tracking systems, email archives, and the like. OUTPUT ------ -If '-v' is specified, the script reports what it is doing. +If `-v` is specified, the script reports what it is doing. Otherwise, success is indicated the Unix way, i.e. by simply exiting with a zero exit status. diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index db4d7a917c..a336ae5f6f 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -54,7 +54,7 @@ Print usage information and exit You can specify a list of allowed directories. If no directories are given, all are allowed. This is an additional restriction, gitcvs access still needs to be enabled by the `gitcvs.enabled` config option -unless '--export-all' was given, too. +unless `--export-all` was given, too. DESCRIPTION @@ -332,7 +332,7 @@ To get a checkout with the Eclipse CVS client: 3. Browse the 'modules' available. It will give you a list of the heads in the repository. You will not be able to browse the tree from there. Only the heads. -4. Pick 'HEAD' when it asks what branch/tag to check out. Untick the +4. Pick `HEAD` when it asks what branch/tag to check out. Untick the "launch commit wizard" to avoid committing the .project file. Protocol notes: If you are using anonymous access via pserver, just select that. @@ -402,12 +402,12 @@ Exports and tagging (tags and branches) are not supported at this stage. CRLF Line Ending Conversions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default the server leaves the '-k' mode blank for all files, +By default the server leaves the `-k` mode blank for all files, which causes the CVS client to treat them as a text files, subject to end-of-line conversion on some platforms. You can make the server use the end-of-line conversion attributes to -set the '-k' modes for files by setting the `gitcvs.usecrlfattr` +set the `-k` modes for files by setting the `gitcvs.usecrlfattr` config variable. See linkgit:gitattributes[5] for more information about end-of-line conversion. @@ -415,9 +415,9 @@ Alternatively, if `gitcvs.usecrlfattr` config is not enabled or the attributes do not allow automatic detection for a filename, then the server uses the `gitcvs.allBinary` config for the default setting. If `gitcvs.allBinary` is set, then file not otherwise -specified will default to '-kb' mode. Otherwise the '-k' mode +specified will default to '-kb' mode. Otherwise the `-k` mode is left blank. But if `gitcvs.allBinary` is set to "guess", then -the correct '-k' mode will be guessed based on the contents of +the correct `-k` mode will be guessed based on the contents of the file. For best consistency with 'cvs', it is probably best to override the diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index a69b3616ec..3c91db7bed 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -30,7 +30,7 @@ that service if it is enabled. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn't explicitly been marked -for export this way (unless the '--export-all' parameter is specified). If you +for export this way (unless the `--export-all` parameter is specified). If you pass some directory paths as 'git daemon' arguments, you can further restrict the offers to a whitelist comprising of those. @@ -90,10 +90,10 @@ OPTIONS is not supported, then --listen=hostname is also not supported and --listen must be given an IPv4 address. Can be given more than once. - Incompatible with '--inetd' option. + Incompatible with `--inetd` option. --port=<n>:: - Listen on an alternative port. Incompatible with '--inetd' option. + Listen on an alternative port. Incompatible with `--inetd` option. --init-timeout=<n>:: Timeout (in seconds) between the moment the connection is established @@ -188,7 +188,7 @@ Git configuration files in that directory are readable by `<user>`. arguments. The external command can decide to decline the service by exiting with a non-zero status (or to allow it by exiting with a zero status). It can also look at the $REMOTE_ADDR - and $REMOTE_PORT environment variables to learn about the + and `$REMOTE_PORT` environment variables to learn about the requestor when making this decision. + The external command can optionally write a single line to its @@ -296,7 +296,7 @@ they correspond to these IP addresses. selectively enable/disable services per repository:: To enable 'git archive --remote' and disable 'git fetch' against a repository, have the following in the configuration file in the - repository (that is the file 'config' next to 'HEAD', 'refs' and + repository (that is the file 'config' next to `HEAD`, 'refs' and 'objects'). + ---------------------------------------------------------------- diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index c8f28c8c86..e4ac448ff5 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -154,7 +154,7 @@ is found, its name will be output and searching will stop. If an exact match was not found, 'git describe' will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an -abbreviation of the input commit-ish's SHA-1. If '--first-parent' was +abbreviation of the input commit-ish's SHA-1. If `--first-parent` was specified then the walk will only consider the first parent of each commit. diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index a86cf62e68..a171506952 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -40,13 +40,13 @@ include::diff-format.txt[] Operating Modes --------------- You can choose whether you want to trust the index file entirely -(using the '--cached' flag) or ask the diff logic to show any files +(using the `--cached` flag) or ask the diff logic to show any files that don't match the stat state as being "tentatively changed". Both of these operations are very useful indeed. Cached Mode ----------- -If '--cached' is specified, it allows you to ask: +If `--cached` is specified, it allows you to ask: show me the differences between HEAD and the current index contents (the ones I'd write using 'git write-tree') diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 1439486e40..7870e175b7 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -43,11 +43,11 @@ include::diff-options.txt[] show tree entry itself as well as subtrees. Implies -r. --root:: - When '--root' is specified the initial commit will be shown as a big + When `--root` is specified the initial commit will be shown as a big creation event. This is equivalent to a diff against the NULL tree. --stdin:: - When '--stdin' is specified, the command does not take + When `--stdin` is specified, the command does not take <tree-ish> arguments from the command line. Instead, it reads lines containing either two <tree>, one <commit>, or a list of <commit> from its standard input. (Use a single space @@ -70,13 +70,13 @@ commits (but not trees). By default, 'git diff-tree --stdin' does not show differences for merge commits. With this flag, it shows differences to that commit from all of its parents. See - also '-c'. + also `-c`. -s:: By default, 'git diff-tree --stdin' shows differences, - either in machine-readable form (without '-p') or in patch - form (with '-p'). This output can be suppressed. It is - only useful with '-v' flag. + either in machine-readable form (without `-p`) or in patch + form (with `-p`). This output can be suppressed. It is + only useful with `-v` flag. -v:: This flag causes 'git diff-tree --stdin' to also show @@ -91,17 +91,17 @@ include::pretty-options.txt[] -c:: This flag changes the way a merge commit is displayed (which means it is useful only when the command is given - one <tree-ish>, or '--stdin'). It shows the differences + one <tree-ish>, or `--stdin`). It shows the differences from each of the parents to the merge result simultaneously instead of showing pairwise diff between a parent and the - result one at a time (which is what the '-m' option does). + result one at a time (which is what the `-m` option does). Furthermore, it lists only files which were modified from all parents. --cc:: This flag changes the way a merge commit patch is displayed, - in a similar way to the '-c' option. It implies the '-c' - and '-p' options and further compresses the patch output + in a similar way to the `-c` option. It implies the `-c` + and `-p` options and further compresses the patch output by omitting uninteresting hunks whose the contents in the parents have only two variants and the merge result picks one of them without modification. When all hunks are uninteresting, the commit diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 333cf6ff91..224fb3090b 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -98,7 +98,7 @@ instead. `--no-symlinks` is the default on Windows. invoked diff tool returns a non-zero exit code. + 'git-difftool' will forward the exit code of the invoked tool when -'--trust-exit-code' is used. +`--trust-exit-code` is used. See linkgit:git-diff[1] for the full list of supported options. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 66910aa2fa..2b762654bf 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -136,6 +136,8 @@ Performance and Compression Tuning Maximum size of each output packfile. The default is unlimited. +fastimport.unpackLimit:: + See linkgit:git-config[1] Performance ----------- @@ -1054,7 +1056,7 @@ relative-marks:: no-relative-marks:: force:: Act as though the corresponding command-line option with - a leading '--' was passed on the command line + a leading `--` was passed on the command line (see OPTIONS, above). import-marks:: @@ -1105,7 +1107,7 @@ options the user may specify to git fast-import itself. The `<option>` part of the command may contain any of the options listed in the OPTIONS section that do not change import semantics, -without the leading '--' and is treated in the same way. +without the leading `--` and is treated in the same way. Option commands must be the first commands on the input (not counting feature commands), to give an option command after any non-option diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 239623cc24..24417ee3a6 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -41,13 +41,13 @@ OPTIONS option, then the refs from stdin are processed after those on the command line. + -If '--stateless-rpc' is specified together with this option then +If `--stateless-rpc` is specified together with this option then the list of refs must be in packet format (pkt-line). Each ref must be in a separate packet, and the list must end with a flush packet. -q:: --quiet:: - Pass '-q' flag to 'git unpack-objects'; this makes the + Pass `-q` flag to 'git unpack-objects'; this makes the cloning process less verbose. -k:: diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index efe56e0808..9e4216999d 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -99,6 +99,57 @@ The latter use of the `remote.<repository>.fetch` values can be overridden by giving the `--refmap=<refspec>` parameter(s) on the command line. +OUTPUT +------ + +The output of "git fetch" depends on the transport method used; this +section describes the output when fetching over the Git protocol +(either locally or via ssh) and Smart HTTP protocol. + +The status of the fetch is output in tabular form, with each line +representing the status of a single ref. Each line is of the form: + +------------------------------- + <flag> <summary> <from> -> <to> [<reason>] +------------------------------- + +The status of up-to-date refs is shown only if the --verbose option is +used. + +In compact output mode, specified with configuration variable +fetch.output, if either entire `<from>` or `<to>` is found in the +other string, it will be substituted with `*` in the other string. For +example, `master -> origin/master` becomes `master -> origin/*`. + +flag:: + A single character indicating the status of the ref: +(space);; for a successfully fetched fast-forward; +`+`;; for a successful forced update; +`-`;; for a successfully pruned ref; +`t`;; for a successful tag update; +`*`;; for a successfully fetched new ref; +`!`;; for a ref that was rejected or failed to update; and +`=`;; for a ref that was up to date and did not need fetching. + +summary:: + For a successfully fetched ref, the summary shows the old and new + values of the ref in a form suitable for using as an argument to + `git log` (this is `<old>..<new>` in most cases, and + `<old>...<new>` for forced non-fast-forward updates). + +from:: + The name of the remote ref being fetched from, minus its + `refs/<type>/` prefix. In the case of deletion, the name of + the remote ref is "(none)". + +to:: + The name of the local ref being updated, minus its + `refs/<type>/` prefix. + +reason:: + A human-readable explanation. In the case of successfully fetched + refs, no explanation is needed. For a failed ref, the reason for + failure is described. EXAMPLES -------- diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 003731f6a9..0a09698c03 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -52,7 +52,7 @@ if different from the rewritten ones, will be stored in the namespace Note that since this operation is very I/O expensive, it might be a good idea to redirect the temporary directory off-disk with the -'-d' option, e.g. on tmpfs. Reportedly the speedup is very noticeable. +`-d` option, e.g. on tmpfs. Reportedly the speedup is very noticeable. Filters @@ -61,7 +61,7 @@ Filters The filters are applied in the order as listed below. The <command> argument is always evaluated in the shell context using the 'eval' command (with the notable exception of the commit filter, for technical reasons). -Prior to that, the $GIT_COMMIT environment variable will be set to contain +Prior to that, the `$GIT_COMMIT` environment variable will be set to contain the id of the commit being rewritten. Also, GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, and GIT_COMMITTER_DATE are taken from the current commit and exported to @@ -171,7 +171,7 @@ to other tags will be rewritten to point to the underlying commit. untouched. This switch allow git-filter-branch to ignore such commits. Though, this switch only applies for commits that have one and only one parent, it will hence keep merges points. Also, this - option is not compatible with the use of '--commit-filter'. Though you + option is not compatible with the use of `--commit-filter`. Though you just need to use the function 'git_commit_non_empty_tree "$@"' instead of the `git commit-tree "$@"` idiom in your commit filter to make that happen. @@ -197,7 +197,7 @@ to other tags will be rewritten to point to the underlying commit. <rev-list options>...:: Arguments for 'git rev-list'. All positive refs included by these options are rewritten. You may also specify options - such as '--all', but you must use '--' to separate them from + such as `--all`, but you must use `--` to separate them from the 'git filter-branch' options. Implies <<Remap_to_ancestor>>. diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index d9d406dcfb..f57e69bc83 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -142,7 +142,7 @@ align:: <width> and <position> used instead. For instance, `%(align:<width>,<position>)`. If the contents length is more than the width then no alignment is performed. If used with - '--quote' everything in between %(align:...) and %(end) is + `--quote` everything in between %(align:...) and %(end) is quoted, but if nested then only the topmost level performs quoting. diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index bdeecd59e0..9624c84a65 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -58,7 +58,7 @@ output, unless the `--stdout` option is specified. If `-o` is specified, output files are created in <dir>. Otherwise they are created in the current working directory. The default path -can be set with the 'format.outputDirectory' configuration option. +can be set with the `format.outputDirectory` configuration option. The `-o` option takes precedence over `format.outputDirectory`. To store patches in the current working directory even when `format.outputDirectory` points elsewhere, use `-o .`. @@ -146,9 +146,9 @@ series, where the head is chosen from the cover letter, the `--in-reply-to`, and the first patch mail, in this order. 'deep' threading makes every mail a reply to the previous one. + -The default is `--no-thread`, unless the 'format.thread' configuration +The default is `--no-thread`, unless the `format.thread` configuration is set. If `--thread` is specified without a style, it defaults to the -style specified by 'format.thread' if any, or else `shallow`. +style specified by `format.thread` if any, or else `shallow`. + Beware that the default for 'git send-email' is to thread emails itself. If you want `git format-patch` to take care of threading, you diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 84ee92e158..7fc68eb319 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -95,7 +95,7 @@ DISCUSSION git-fsck tests SHA-1 and general object sanity, and it does full tracking of the resulting reachability and everything else. It prints out any corruption it finds (missing or bad objects), and if you use the -'--unreachable' flag it will also print out objects that exist but that +`--unreachable` flag it will also print out objects that exist but that aren't reachable from any of the specified head nodes (or the default set, as mentioned above). diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index fa1510480a..bed60f471c 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -82,13 +82,13 @@ automatic consolidation of packs. Configuration ------------- -The optional configuration variable 'gc.reflogExpire' can be +The optional configuration variable `gc.reflogExpire` can be set to indicate how long historical entries within each branch's reflog should remain available in this repository. The setting is expressed as a length of time, for example '90 days' or '3 months'. It defaults to '90 days'. -The optional configuration variable 'gc.reflogExpireUnreachable' +The optional configuration variable `gc.reflogExpireUnreachable` can be set to indicate how long historical reflog entries which are not part of the current branch should remain available in this repository. These types of entries are generally created as @@ -107,30 +107,30 @@ branches: reflogExpireUnreachable = 3 days ------------ -The optional configuration variable 'gc.rerereResolved' indicates +The optional configuration variable `gc.rerereResolved` indicates how long records of conflicted merge you resolved earlier are kept. This defaults to 60 days. -The optional configuration variable 'gc.rerereUnresolved' indicates +The optional configuration variable `gc.rerereUnresolved` indicates how long records of conflicted merge you have not resolved are kept. This defaults to 15 days. -The optional configuration variable 'gc.packRefs' determines if +The optional configuration variable `gc.packRefs` determines if 'git gc' runs 'git pack-refs'. This can be set to "notbare" to enable it within all non-bare repos or it can be set to a boolean value. This defaults to true. -The optional configuration variable 'gc.aggressiveWindow' controls how +The optional configuration variable `gc.aggressiveWindow` controls how much time is spent optimizing the delta compression of the objects in the repository when the --aggressive option is specified. The larger the value, the more time is spent optimizing the delta compression. See the documentation for the --window' option in linkgit:git-repack[1] for more details. This defaults to 250. -Similarly, the optional configuration variable 'gc.aggressiveDepth' +Similarly, the optional configuration variable `gc.aggressiveDepth` controls --depth option in linkgit:git-repack[1]. This defaults to 250. -The optional configuration variable 'gc.pruneExpire' controls how old +The optional configuration variable `gc.pruneExpire` controls how old the unreferenced loose objects have to be before they are pruned. The default is "2 weeks ago". diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index cb0f6cf678..0ecea6e491 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -41,17 +41,17 @@ CONFIGURATION ------------- grep.lineNumber:: - If set to true, enable '-n' option by default. + If set to true, enable `-n` option by default. grep.patternType:: Set the default matching behavior. Using a value of 'basic', 'extended', - 'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp', - '--fixed-strings', or '--perl-regexp' option accordingly, while the + 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`, + `--fixed-strings`, or `--perl-regexp` option accordingly, while the value 'default' will return to the default matching behavior. grep.extendedRegexp:: - If set to true, enable '--extended-regexp' option by default. This - option is ignored when the 'grep.patternType' option is set to a value + If set to true, enable `--extended-regexp` option by default. This + option is ignored when the `grep.patternType` option is set to a value other than 'default'. grep.threads:: @@ -59,7 +59,7 @@ grep.threads:: 8 threads are used by default (for now). grep.fullName:: - If set to true, enable '--full-name' option by default. + If set to true, enable `--full-name` option by default. grep.fallbackToNoIndex:: If set to true, fall back to git grep --no-index if git grep diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index 8144527ae0..c1a3e8bf07 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -35,7 +35,7 @@ blame:: browser:: Start a tree browser showing all files in the specified - commit (or 'HEAD' by default). Files selected through the + commit (or `HEAD` by default). Files selected through the browser are opened in the blame viewer. citool:: diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 3956525218..40d328a4b3 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -18,10 +18,10 @@ With no options and no COMMAND or GUIDE given, the synopsis of the 'git' command and a list of the most commonly used Git commands are printed on the standard output. -If the option '--all' or '-a' is given, all available commands are +If the option `--all` or `-a` is given, all available commands are printed on the standard output. -If the option '--guide' or '-g' is given, a list of the useful +If the option `--guide` or `-g` is given, a list of the useful Git guides is also printed on the standard output. If a command, or a guide, is given, a manual page for that command or @@ -57,10 +57,10 @@ OPTIONS --man:: Display manual page for the command in the 'man' format. This option may be used to override a value set in the - 'help.format' configuration variable. + `help.format` configuration variable. + By default the 'man' program will be used to display the manual page, -but the 'man.viewer' configuration variable may be used to choose +but the `man.viewer` configuration variable may be used to choose other display programs (see below). -w:: @@ -69,7 +69,7 @@ other display programs (see below). format. A web browser will be used for that purpose. + The web browser can be specified using the configuration variable -'help.browser', or 'web.browser' if the former is not set. If none of +`help.browser`, or `web.browser` if the former is not set. If none of these config variables is set, the 'git web{litdd}browse' helper script (called by 'git help') will pick a suitable default. See linkgit:git-web{litdd}browse[1] for more information about this. @@ -80,7 +80,7 @@ CONFIGURATION VARIABLES help.format ~~~~~~~~~~~ -If no command-line option is passed, the 'help.format' configuration +If no command-line option is passed, the `help.format` configuration variable will be checked. The following values are supported for this variable; they make 'git help' behave as their corresponding command- line option: @@ -92,7 +92,7 @@ line option: help.browser, web.browser and browser.<tool>.path ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 'help.browser', 'web.browser' and 'browser.<tool>.path' will also +The `help.browser`, `web.browser` and `browser.<tool>.path` will also be checked if the 'web' format is chosen (either by command-line option or configuration variable). See '-w|--web' in the OPTIONS section above and linkgit:git-web{litdd}browse[1]. @@ -100,7 +100,7 @@ section above and linkgit:git-web{litdd}browse[1]. man.viewer ~~~~~~~~~~ -The 'man.viewer' configuration variable will be checked if the 'man' +The `man.viewer` configuration variable will be checked if the 'man' format is chosen. The following values are currently supported: * "man": use the 'man' program as usual, @@ -110,9 +110,9 @@ format is chosen. The following values are currently supported: tab (see 'Note about konqueror' below). Values for other tools can be used if there is a corresponding -'man.<tool>.cmd' configuration entry (see below). +`man.<tool>.cmd` configuration entry (see below). -Multiple values may be given to the 'man.viewer' configuration +Multiple values may be given to the `man.viewer` configuration variable. Their corresponding programs will be tried in the order listed in the configuration file. @@ -128,14 +128,14 @@ will try to use konqueror first. But this may fail (for example, if DISPLAY is not set) and in that case emacs' woman mode will be tried. If everything fails, or if no viewer is configured, the viewer specified -in the GIT_MAN_VIEWER environment variable will be tried. If that +in the `GIT_MAN_VIEWER` environment variable will be tried. If that fails too, the 'man' program will be tried anyway. man.<tool>.path ~~~~~~~~~~~~~~~ You can explicitly provide a full path to your preferred man viewer by -setting the configuration variable 'man.<tool>.path'. For example, you +setting the configuration variable `man.<tool>.path`. For example, you can configure the absolute path to konqueror by setting 'man.konqueror.path'. Otherwise, 'git help' assumes the tool is available in PATH. @@ -143,9 +143,9 @@ available in PATH. man.<tool>.cmd ~~~~~~~~~~~~~~ -When the man viewer, specified by the 'man.viewer' configuration +When the man viewer, specified by the `man.viewer` configuration variables, is not among the supported ones, then the corresponding -'man.<tool>.cmd' configuration variable will be looked up. If this +`man.<tool>.cmd` configuration variable will be looked up. If this variable exists then the specified tool will be treated as a custom command and a shell eval will be used to run the command with the man page passed as arguments. @@ -153,7 +153,7 @@ page passed as arguments. Note about konqueror ~~~~~~~~~~~~~~~~~~~~ -When 'konqueror' is specified in the 'man.viewer' configuration +When 'konqueror' is specified in the `man.viewer` configuration variable, we launch 'kfmclient' to try to open the man page on an already opened konqueror in a new tab if possible. @@ -176,7 +176,7 @@ Note about git config --global ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Note that all these configuration variables should probably be set -using the '--global' flag, for example like this: +using the `--global` flag, for example like this: ------------------------------------------------ $ git config --global help.format web diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index 9268fb6b1e..bb0db195ce 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -21,7 +21,7 @@ pushing using the smart HTTP protocol. It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn't explicitly been marked for export this way (unless the -GIT_HTTP_EXPORT_ALL environmental variable is set). +`GIT_HTTP_EXPORT_ALL` environmental variable is set). By default, only the `upload-pack` service is enabled, which serves 'git fetch-pack' and 'git ls-remote' clients, which are invoked from @@ -241,7 +241,7 @@ $HTTP["url"] =~ "^/git/private" { ENVIRONMENT ----------- -'git http-backend' relies upon the CGI environment variables set +'git http-backend' relies upon the `CGI` environment variables set by the invoking web server, including: * PATH_INFO (if GIT_PROJECT_ROOT is set, otherwise PATH_TRANSLATED) @@ -251,7 +251,7 @@ by the invoking web server, including: * QUERY_STRING * REQUEST_METHOD -The GIT_HTTP_EXPORT_ALL environmental variable may be passed to +The `GIT_HTTP_EXPORT_ALL` environmental variable may be passed to 'git-http-backend' to bypass the check for the "git-daemon-export-ok" file in each repository before allowing export of that repository. @@ -269,7 +269,7 @@ GIT_COMMITTER_EMAIL to '$\{REMOTE_USER}@http.$\{REMOTE_ADDR\}', ensuring that any reflogs created by 'git-receive-pack' contain some identifying information of the remote user who performed the push. -All CGI environment variables are available to each of the hooks +All `CGI` environment variables are available to each of the hooks invoked by the 'git-receive-pack'. GIT diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index 2e67362bd4..2aceb6f26d 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -81,13 +81,13 @@ destination side. exist in the set of remote refs; the ref matched <src> locally is used as the name of the destination. -Without '--force', the <src> ref is stored at the remote only if +Without `--force`, the <src> ref is stored at the remote only if <dst> does not exist, or <dst> is a proper subset (i.e. an ancestor) of <src>. This check, known as "fast-forward check", is performed in order to avoid accidentally overwriting the remote ref and lose other peoples' commits from there. -With '--force', the fast-forward check is disabled for all refs. +With `--force`, the fast-forward check is disabled for all refs. Optionally, a <ref> parameter can be prefixed with a plus '+' sign to disable the fast-forward check only on that ref. diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 6364e5dc45..9d27197de8 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -47,7 +47,7 @@ Only print error and warning messages; all other output will be suppressed. --bare:: -Create a bare repository. If GIT_DIR environment is not set, it is set to the +Create a bare repository. If `GIT_DIR` environment is not set, it is set to the current working directory. --template=<template_directory>:: diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index cc75b25022..e8ecdbf927 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -80,8 +80,8 @@ You may specify configuration in your .git/config ----------------------------------------------------------------------- -If the configuration variable 'instaweb.browser' is not set, -'web.browser' will be used instead if it is defined. See +If the configuration variable `instaweb.browser` is not set, +`web.browser` will be used instead if it is defined. See linkgit:git-web{litdd}browse[1] for more information about this. SEE ALSO diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index a77b901f1d..93d1db6528 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -219,7 +219,7 @@ Signed-off-by: Alice <alice@example.com> Signed-off-by: Bob <bob@example.com> ------------ -* Use the '--in-place' option to edit a message file in place: +* Use the `--in-place` option to edit a message file in place: + ------------ $ cat msg.txt diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index dec379b3e2..32246fdb00 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -198,12 +198,16 @@ log.showRoot:: `git log -p` output would be shown without a diff attached. The default is `true`. +log.showSignature:: + If `true`, `git log` and related commands will act as if the + `--show-signature` option was passed to them. + mailmap.*:: See linkgit:git-shortlog[1]. notes.displayRef:: Which refs, in addition to the default set by `core.notesRef` - or 'GIT_NOTES_REF', to read notes from when showing commit + or `GIT_NOTES_REF`, to read notes from when showing commit messages with the `log` family of commands. See linkgit:git-notes[1]. + @@ -212,7 +216,7 @@ multiple times. A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored. + This setting can be disabled by the `--no-notes` option, -overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable, +overridden by the `GIT_NOTES_DISPLAY_REF` environment variable, and overridden by the `--notes=<ref>` option. GIT diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 75c3f4157d..078b556665 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -175,7 +175,7 @@ followed by the ("attr/<eolattr>"). Output ------ -'git ls-files' just outputs the filenames unless '--stage' is specified in +'git ls-files' just outputs the filenames unless `--stage` is specified in which case it outputs: [<tag> ]<mode> <object> <stage> <file> diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 16e87fd6dd..dbc91f98ff 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -20,16 +20,16 @@ in the current working directory. Note that: - the behaviour is slightly different from that of "/bin/ls" in that the '<path>' denotes just a list of patterns to match, e.g. so specifying - directory name (without '-r') will behave differently, and order of the + directory name (without `-r`) will behave differently, and order of the arguments does not matter. - the behaviour is similar to that of "/bin/ls" in that the '<path>' is taken as relative to the current working directory. E.g. when you are in a directory 'sub' that has a directory 'dir', you can run 'git ls-tree -r HEAD dir' to list the contents of the tree (that is - 'sub/dir' in 'HEAD'). You don't want to give a tree that is not at the + 'sub/dir' in `HEAD`). You don't want to give a tree that is not at the root level (e.g. `git ls-tree -r HEAD:sub dir`) in this case, as that - would result in asking for 'sub/sub/dir' in the 'HEAD' commit. + would result in asking for 'sub/sub/dir' in the `HEAD` commit. However, the current working directory can be ignored by passing --full-tree option. @@ -46,7 +46,7 @@ OPTIONS -t:: Show tree entries even when going to recurse them. Has no effect - if '-r' was not passed. '-d' implies '-t'. + if `-r` was not passed. `-d` implies `-t`. -l:: --long:: diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index 4d1b871d96..e3b2a88c4b 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -8,7 +8,8 @@ git-mailsplit - Simple UNIX mbox splitter program SYNOPSIS -------- [verse] -'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [(<mbox>|<Maildir>)...] +'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] [--mboxrd] + -o<directory> [--] [(<mbox>|<Maildir>)...] DESCRIPTION ----------- @@ -47,6 +48,10 @@ OPTIONS --keep-cr:: Do not remove `\r` from lines ending with `\r\n`. +--mboxrd:: + Input is of the "mboxrd" format and "^>+From " line escaping is + reversed. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index 5c6ebdfad9..c3616e7711 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -32,7 +32,7 @@ OPTIONS --batch:: Allow building of more than one tree object before exiting. Each tree is separated by as single blank line. The final new-line is - optional. Note - if the '-z' option is used, lines are terminated + optional. Note - if the `-z` option is used, lines are terminated with NUL. GIT diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index e4531325cd..79449bf98f 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -32,10 +32,10 @@ OPTIONS --force:: Force renaming or moving of a file even if the target exists -k:: - Skip move or rename actions which would lead to an error + Skip move or rename actions which would lead to an error condition. An error happens when a source is neither existing nor controlled by Git, or when it would overwrite an existing - file unless '-f' is given. + file unless `-f` is given. -n:: --dry-run:: Do nothing; only show what would happen diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 9c4fd6812c..be7db3048d 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -152,7 +152,7 @@ OPTIONS -c <object>:: --reedit-message=<object>:: - Like '-C', but with '-c' the editor is invoked, so that + Like '-C', but with `-c` the editor is invoked, so that the user can further edit the note message. --allow-empty:: @@ -161,7 +161,7 @@ OPTIONS --ref <ref>:: Manipulate the notes tree in <ref>. This overrides - 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref + `GIT_NOTES_REF` and the "core.notesRef" configuration. The ref specifies the full refname when it begins with `refs/notes/`; when it begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed to form a full name of the ref. @@ -333,10 +333,10 @@ notes.<name>.mergeStrategy:: notes.displayRef:: Which ref (or refs, if a glob or specified more than once), in addition to the default set by `core.notesRef` or - 'GIT_NOTES_REF', to read notes from when showing commit + `GIT_NOTES_REF`, to read notes from when showing commit messages with the 'git log' family of commands. This setting can be overridden on the command line or by the - 'GIT_NOTES_DISPLAY_REF' environment variable. + `GIT_NOTES_DISPLAY_REF` environment variable. See linkgit:git-log[1]. notes.rewrite.<command>:: @@ -345,7 +345,7 @@ notes.rewrite.<command>:: notes from the original to the rewritten commit. Defaults to `true`. See also "`notes.rewriteRef`" below. + -This setting can be overridden by the 'GIT_NOTES_REWRITE_REF' +This setting can be overridden by the `GIT_NOTES_REWRITE_REF` environment variable. notes.rewriteMode:: @@ -366,33 +366,33 @@ notes.rewriteRef:: Does not have a default value; you must configure this variable to enable note rewriting. + -Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. +Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable. ENVIRONMENT ----------- -'GIT_NOTES_REF':: +`GIT_NOTES_REF`:: Which ref to manipulate notes from, instead of `refs/notes/commits`. This overrides the `core.notesRef` setting. -'GIT_NOTES_DISPLAY_REF':: +`GIT_NOTES_DISPLAY_REF`:: Colon-delimited list of refs or globs indicating which refs, in addition to the default from `core.notesRef` or - 'GIT_NOTES_REF', to read notes from when showing commit + `GIT_NOTES_REF`, to read notes from when showing commit messages. This overrides the `notes.displayRef` setting. + A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored. -'GIT_NOTES_REWRITE_MODE':: +`GIT_NOTES_REWRITE_MODE`:: When copying notes during a rewrite, what to do if the target commit already has a note. Must be one of `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`. This overrides the `core.rewriteMode` setting. -'GIT_NOTES_REWRITE_REF':: +`GIT_NOTES_REWRITE_REF`:: When rewriting commits, which notes to copy from the original to the rewritten commit. Must be a colon-delimited list of refs or globs. diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 88ba42b455..c83aaf39c3 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -104,7 +104,7 @@ $ git p4 sync //path/in/your/perforce/depot ------------ This imports the specified depot into 'refs/remotes/p4/master' in an existing Git repository. The -'--branch' option can be used to specify a different branch to +`--branch` option can be used to specify a different branch to be used for the p4 content. If a Git repository includes branches 'refs/remotes/origin/p4', these @@ -114,7 +114,7 @@ from a Git remote, this can be useful in a multi-developer environment. If there are multiple branches, doing 'git p4 sync' will automatically use the "BRANCH DETECTION" algorithm to try to partition new changes -into the right branch. This can be overridden with the '--branch' +into the right branch. This can be overridden with the `--branch` option to specify just a single branch to update. @@ -134,7 +134,7 @@ Submit ~~~~~~ Submitting changes from a Git repository back to the p4 repository requires a separate p4 client workspace. This should be specified -using the 'P4CLIENT' environment variable or the Git configuration +using the `P4CLIENT` environment variable or the Git configuration variable 'git-p4.client'. The p4 client must exist, but the client root will be created and populated if it does not already exist. @@ -150,10 +150,10 @@ $ git p4 submit topicbranch ------------ The upstream reference is generally 'refs/remotes/p4/master', but can -be overridden using the '--origin=' command-line option. +be overridden using the `--origin=` command-line option. The p4 changes will be created as the user invoking 'git p4 submit'. The -'--preserve-user' option will cause ownership to be modified +`--preserve-user` option will cause ownership to be modified according to the author of the Git commit. This option requires admin privileges in p4, which can be granted using 'p4 protect'. @@ -166,7 +166,7 @@ General options All commands except clone accept these options. --git-dir <dir>:: - Set the 'GIT_DIR' environment variable. See linkgit:git[1]. + Set the `GIT_DIR` environment variable. See linkgit:git[1]. -v:: --verbose:: @@ -221,7 +221,7 @@ Git repository: where they will be treated as remote-tracking branches by linkgit:git-branch[1] and other commands. This option instead puts p4 branches in 'refs/heads/p4/'. Note that future - sync operations must specify '--import-local' as well so that + sync operations must specify `--import-local` as well so that they can find the p4 branches in refs/heads. --max-changes <n>:: @@ -245,7 +245,7 @@ Git repository: default, involves removing the entire depot path. With this option, the full p4 depot path is retained in Git. For example, path '//depot/main/foo/bar.c', when imported from - '//depot/main/', becomes 'foo/bar.c'. With '--keep-path', the + '//depot/main/', becomes 'foo/bar.c'. With `--keep-path`, the Git path is instead 'depot/main/foo/bar.c'. --use-client-spec:: @@ -275,7 +275,7 @@ These options can be used to modify 'git p4 submit' behavior. --origin <commit>:: Upstream location from which commits are identified to submit to p4. By default, this is the most recent p4 commit reachable - from 'HEAD'. + from `HEAD`. -M:: Detect renames. See linkgit:git-diff[1]. Renames will be @@ -341,7 +341,7 @@ p4 revision specifier on the end: Import all changes from both named depot paths into a single repository. Only files below these directories are included. There is not a subdirectory in Git for each "proj1" and "proj2". - You must use the '--destination' option when specifying more + You must use the `--destination` option when specifying more than one depot path. The revision specifier must be specified identically on each depot path. If there are files in the depot paths with the same name, the path with the most recently @@ -355,7 +355,7 @@ CLIENT SPEC The p4 client specification is maintained with the 'p4 client' command and contains among other fields, a View that specifies how the depot is mapped into the client repository. The 'clone' and 'sync' commands -can consult the client spec when given the '--use-client-spec' option or +can consult the client spec when given the `--use-client-spec` option or when the useClientSpec variable is true. After 'git p4 clone', the useClientSpec variable is automatically set in the repository configuration file. This allows future 'git p4 submit' commands to @@ -390,7 +390,7 @@ different areas in the tree, and indicate related content. 'git p4' can use these mappings to determine branch relationships. If you have a repository where all the branches of interest exist as -subdirectories of a single depot path, you can use '--detect-branches' +subdirectories of a single depot path, you can use `--detect-branches` when cloning or syncing to have 'git p4' automatically find subdirectories in p4, and to generate these as branches in Git. @@ -507,7 +507,7 @@ git-p4.labelImportRegexp:: git-p4.useClientSpec:: Specify that the p4 client spec should be used to identify p4 depot paths of interest. This is equivalent to specifying the - option '--use-client-spec'. See the "CLIENT SPEC" section above. + option `--use-client-spec`. See the "CLIENT SPEC" section above. This variable is a boolean, not the name of a p4 client. git-p4.pathEncoding:: diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index cf6ee4a4df..93c3527f0c 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -137,8 +137,8 @@ already exists on the remote side. and also push annotated tags in `refs/tags` that are missing from the remote but are pointing at commit-ish that are reachable from the refs being pushed. This can also be specified - with configuration variable 'push.followTags'. For more - information, see 'push.followTags' in linkgit:git-config[1]. + with configuration variable `push.followTags`. For more + information, see `push.followTags` in linkgit:git-config[1]. --[no-]signed:: --sign=(true|false|if-asked):: @@ -240,7 +240,7 @@ origin +master` to force a push to the `master` branch). See the For every branch that is up to date or successfully pushed, add upstream (tracking) reference, used by argument-less linkgit:git-pull[1] and other commands. For more information, - see 'branch.<name>.merge' in linkgit:git-config[1]. + see `branch.<name>.merge` in linkgit:git-config[1]. --[no-]thin:: These options are passed to linkgit:git-send-pack[1]. A thin transfer @@ -275,7 +275,7 @@ origin +master` to force a push to the `master` branch). See the all submodules that changed in the revisions to be pushed will be pushed. If on-demand was not able to push all necessary revisions it will also be aborted and exit with non-zero status. A value of - 'no' or using '--no-recurse-submodules' can be used to override the + 'no' or using `--no-recurse-submodules` can be used to override the push.recurseSubmodules configuration variable when no submodule recursion is required. diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index ff633b0db7..8cf952b4de 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -46,14 +46,14 @@ OPTIONS The directory to find the quilt patches. + The default for the patch directory is patches -or the value of the $QUILT_PATCHES environment +or the value of the `$QUILT_PATCHES` environment variable. --series <file>:: The quilt series file. + The default for the series file is <patches>/series -or the value of the $QUILT_SERIES environment +or the value of the `$QUILT_SERIES` environment variable. GIT diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 0387b40e0a..de222c81af 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -208,10 +208,10 @@ rebase.stat:: rebase. False by default. rebase.autoSquash:: - If set to true enable '--autosquash' option by default. + If set to true enable `--autosquash` option by default. rebase.autoStash:: - If set to true enable '--autostash' option by default. + If set to true enable `--autostash` option by default. rebase.missingCommitsCheck:: If set to "warn", print warnings about removed commits in @@ -220,7 +220,7 @@ rebase.missingCommitsCheck:: done. "ignore" by default. rebase.instructionFormat:: - Custom commit list format to use during an '--interactive' rebase. + Custom commit list format to use during an `--interactive` rebase. OPTIONS ------- @@ -428,9 +428,9 @@ without an explicit `--interactive`. "fixup! " or "squash! " after the first, in case you referred to an earlier fixup/squash with `git commit --fixup/--squash`. + -This option is only valid when the '--interactive' option is used. +This option is only valid when the `--interactive` option is used. + -If the '--autosquash' option is enabled by default using the +If the `--autosquash` option is enabled by default using the configuration variable `rebase.autoSquash`, this option can be used to override and disable this setting. diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 1d7eceaa93..577b969c1b 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -137,9 +137,9 @@ branches, adds to that list. Retrieves the URLs for a remote. Configurations for `insteadOf` and `pushInsteadOf` are expanded here. By default, only the first URL is listed. + -With '--push', push URLs are queried rather than fetch URLs. +With `--push`, push URLs are queried rather than fetch URLs. + -With '--all', all URLs for the remote will be listed. +With `--all`, all URLs for the remote will be listed. 'set-url':: @@ -147,11 +147,11 @@ Changes URLs for the remote. Sets first URL for remote <name> that matches regex <oldurl> (first URL if no <oldurl> is given) to <newurl>. If <oldurl> doesn't match any URL, an error occurs and nothing is changed. + -With '--push', push URLs are manipulated instead of fetch URLs. +With `--push`, push URLs are manipulated instead of fetch URLs. + -With '--add', instead of changing existing URLs, new URL is added. +With `--add`, instead of changing existing URLs, new URL is added. + -With '--delete', instead of changing existing URLs, all URLs matching +With `--delete`, instead of changing existing URLs, all URLs matching regex <url> are deleted for remote <name>. Trying to delete all non-push URLs is an error. + diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index b9c02ce481..c5975234f4 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -33,7 +33,7 @@ OPTIONS pack everything referenced into a single pack. Especially useful when packing a repository that is used for private development. Use - with '-d'. This will clean up the objects that `git prune` + with `-d`. This will clean up the objects that `git prune` leaves behind, but `git fsck --full --dangling` shows as dangling. + @@ -42,7 +42,7 @@ whole new pack in order to get any contained object, no matter how many other objects in that pack they already have locally. -A:: - Same as `-a`, unless '-d' is used. Then any unreachable + Same as `-a`, unless `-d` is used. Then any unreachable objects in a previous pack become loose, unpacked objects, instead of being left in the old pack. Unreachable objects are never intentionally added to a pack, even when repacking. @@ -128,6 +128,19 @@ other objects in that pack they already have locally. with `-b` or `repack.writeBitmaps`, as it ensures that the bitmapped packfile has the necessary objects. +--unpack-unreachable=<when>:: + When loosening unreachable objects, do not bother loosening any + objects older than `<when>`. This can be used to optimize out + the write of any objects that would be immediately pruned by + a follow-up `git prune`. + +-k:: +--keep-unreachable:: + When used with `-ad`, any unreachable objects from existing + packs will be appended to the end of the packfile instead of + being removed. In addition, any unreachable loose objects will + be packed (and their loose counterparts removed). + Configuration ------------- diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 8fff598fd6..e5c57ae6ef 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -51,7 +51,7 @@ $ git cat-file commit foo shows information about commit 'bar'. -The 'GIT_NO_REPLACE_OBJECTS' environment variable can be set to +The `GIT_NO_REPLACE_OBJECTS` environment variable can be set to achieve the same effect as the `--no-replace-objects` option. OPTIONS diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 573616a04a..837707a8fd 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -24,7 +24,7 @@ from the HEAD commit). Note: 'git revert' is used to record some new commits to reverse the effect of some earlier commits (often only a faulty one). If you want to throw away all uncommitted changes in your working directory, you -should see linkgit:git-reset[1], particularly the '--hard' option. If +should see linkgit:git-reset[1], particularly the `--hard` option. If you want to extract specific files as they were in another commit, you should see linkgit:git-checkout[1], specifically the `git checkout <commit> -- <filename>` syntax. Take care with these alternatives as @@ -37,7 +37,7 @@ OPTIONS For a more complete list of ways to spell commit names, see linkgit:gitrevisions[7]. Sets of commits can also be given but no traversal is done by - default, see linkgit:git-rev-list[1] and its '--no-walk' + default, see linkgit:git-rev-list[1] and its `--no-walk` option. -e:: diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index a88d18604a..642d0ef199 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -47,18 +47,18 @@ Composing --annotate:: Review and edit each patch you're about to send. Default is the value - of 'sendemail.annotate'. See the CONFIGURATION section for - 'sendemail.multiEdit'. + of `sendemail.annotate`. See the CONFIGURATION section for + `sendemail.multiEdit`. --bcc=<address>,...:: Specify a "Bcc:" value for each email. Default is the value of - 'sendemail.bcc'. + `sendemail.bcc`. + This option may be specified multiple times. --cc=<address>,...:: Specify a starting "Cc:" value for each email. - Default is the value of 'sendemail.cc'. + Default is the value of `sendemail.cc`. + This option may be specified multiple times. @@ -66,7 +66,7 @@ This option may be specified multiple times. Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1]) to edit an introductory message for the patch series. + -When '--compose' is used, git send-email will use the From, Subject, and +When `--compose` is used, git send-email will use the From, Subject, and In-Reply-To headers specified in the message. If the body of the message (what you type after the headers and a blank line) only contains blank (or Git: prefixed) lines, the summary won't be sent, but From, Subject, @@ -74,12 +74,12 @@ and In-Reply-To headers will be used unless they are removed. + Missing From or In-Reply-To headers will be prompted for. + -See the CONFIGURATION section for 'sendemail.multiEdit'. +See the CONFIGURATION section for `sendemail.multiEdit`. --from=<address>:: Specify the sender of the emails. If not specified on the command line, - the value of the 'sendemail.from' configuration option is used. If - neither the command-line option nor 'sendemail.from' are set, then the + the value of the `sendemail.from` configuration option is used. If + neither the command-line option nor `sendemail.from` are set, then the user will be prompted for the value. The default for the prompt will be the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not set, as returned by "git var -l". @@ -114,7 +114,7 @@ is not set, this will be prompted for. --to=<address>,...:: Specify the primary recipient of the emails generated. Generally, this will be the upstream maintainer of the project involved. Default is the - value of the 'sendemail.to' configuration value; if that is unspecified, + value of the `sendemail.to` configuration value; if that is unspecified, and --to-cmd is not specified, this will be prompted for. + This option may be specified multiple times. @@ -138,7 +138,7 @@ Note that no attempts whatsoever are made to validate the encoding. can be useful when the repository contains files that contain carriage returns, but makes the raw patch email file (as saved from a MUA) much harder to inspect manually. base64 is even more fool proof, but also - even more opaque. Default is the value of the 'sendemail.transferEncoding' + even more opaque. Default is the value of the `sendemail.transferEncoding` configuration value; if that is unspecified, git will use 8bit and not add a Content-Transfer-Encoding header. @@ -157,20 +157,20 @@ Sending subscribed to a list. In order to use the 'From' address, set the value to "auto". If you use the sendmail binary, you must have suitable privileges for the -f parameter. Default is the value of the - 'sendemail.envelopeSender' configuration variable; if that is + `sendemail.envelopeSender` configuration variable; if that is unspecified, choosing the envelope sender is left to your MTA. --smtp-encryption=<encryption>:: Specify the encryption to use, either 'ssl' or 'tls'. Any other value reverts to plain SMTP. Default is the value of - 'sendemail.smtpEncryption'. + `sendemail.smtpEncryption`. --smtp-domain=<FQDN>:: Specifies the Fully Qualified Domain Name (FQDN) used in the HELO/EHLO command to the SMTP server. Some servers require the FQDN to match your IP address. If not set, git send-email attempts to determine your FQDN automatically. Default is the value of - 'sendemail.smtpDomain'. + `sendemail.smtpDomain`. --smtp-auth=<mechanisms>:: Whitespace-separated list of allowed SMTP-AUTH mechanisms. This setting @@ -182,19 +182,19 @@ $ git send-email --smtp-auth="PLAIN LOGIN GSSAPI" ... + If at least one of the specified mechanisms matches the ones advertised by the SMTP server and if it is supported by the utilized SASL library, the mechanism -is used for authentication. If neither 'sendemail.smtpAuth' nor '--smtp-auth' +is used for authentication. If neither 'sendemail.smtpAuth' nor `--smtp-auth` is specified, all mechanisms supported by the SASL library can be used. --smtp-pass[=<password>]:: Password for SMTP-AUTH. The argument is optional: If no argument is specified, then the empty string is used as - the password. Default is the value of 'sendemail.smtpPass', - however '--smtp-pass' always overrides this value. + the password. Default is the value of `sendemail.smtpPass`, + however `--smtp-pass` always overrides this value. + Furthermore, passwords need not be specified in configuration files or on the command line. If a username has been specified (with -'--smtp-user' or a 'sendemail.smtpUser'), but no password has been -specified (with '--smtp-pass' or 'sendemail.smtpPass'), then +`--smtp-user` or a `sendemail.smtpUser`), but no password has been +specified (with `--smtp-pass` or `sendemail.smtpPass`), then a password is obtained using 'git-credential'. --smtp-server=<host>:: @@ -202,7 +202,7 @@ a password is obtained using 'git-credential'. `smtp.example.com` or a raw IP address). Alternatively it can specify a full pathname of a sendmail-like program instead; the program must support the `-i` option. Default value can - be specified by the 'sendemail.smtpServer' configuration + be specified by the `sendemail.smtpServer` configuration option; the built-in default is `/usr/sbin/sendmail` or `/usr/lib/sendmail` if such program is available, or `localhost` otherwise. @@ -213,11 +213,11 @@ a password is obtained using 'git-credential'. submission port 587, or the common SSL smtp port 465); symbolic port names (e.g. "submission" instead of 587) are also accepted. The port can also be set with the - 'sendemail.smtpServerPort' configuration variable. + `sendemail.smtpServerPort` configuration variable. --smtp-server-option=<option>:: If set, specifies the outgoing SMTP server option to use. - Default value can be specified by the 'sendemail.smtpServerOption' + Default value can be specified by the `sendemail.smtpServerOption` configuration option. + The --smtp-server-option option must be repeated for each option you want @@ -234,13 +234,13 @@ must be used for each option. certificates concatenated together: see verify(1) -CAfile and -CApath for more information on these). Set it to an empty string to disable certificate verification. Defaults to the value of the - 'sendemail.smtpsslcertpath' configuration variable, if set, or the + `sendemail.smtpsslcertpath` configuration variable, if set, or the backing SSL library's compiled-in default otherwise (which should be the best choice on most platforms). --smtp-user=<user>:: - Username for SMTP-AUTH. Default is the value of 'sendemail.smtpUser'; - if a username is not specified (with '--smtp-user' or 'sendemail.smtpUser'), + Username for SMTP-AUTH. Default is the value of `sendemail.smtpUser`; + if a username is not specified (with `--smtp-user` or `sendemail.smtpUser`), then authentication is not attempted. --smtp-debug=0|1:: @@ -261,25 +261,25 @@ Automating Specify a command to execute once per patch file which should generate patch file specific "Cc:" entries. Output of this command must be single email address per line. - Default is the value of 'sendemail.ccCmd' configuration value. + Default is the value of `sendemail.ccCmd` configuration value. --[no-]chain-reply-to:: If this is set, each email will be sent as a reply to the previous email sent. If disabled with "--no-chain-reply-to", all emails after the first will be sent as replies to the first email sent. When using this, it is recommended that the first file given be an overview of the - entire patch series. Disabled by default, but the 'sendemail.chainReplyTo' + entire patch series. Disabled by default, but the `sendemail.chainReplyTo` configuration variable can be used to enable it. --identity=<identity>:: A configuration identity. When given, causes values in the 'sendemail.<identity>' subsection to take precedence over values in the 'sendemail' section. The default identity is - the value of 'sendemail.identity'. + the value of `sendemail.identity`. --[no-]signed-off-by-cc:: If this is set, add emails found in Signed-off-by: or Cc: lines to the - cc list. Default is the value of 'sendemail.signedoffbycc' configuration + cc list. Default is the value of `sendemail.signedoffbycc` configuration value; if that is unspecified, default to --signed-off-by-cc. --[no-]cc-cover:: @@ -312,13 +312,13 @@ Automating - 'all' will suppress all auto cc values. -- + -Default is the value of 'sendemail.suppresscc' configuration value; if +Default is the value of `sendemail.suppresscc` configuration value; if that is unspecified, default to 'self' if --suppress-from is specified, as well as 'body' if --no-signed-off-cc is specified. --[no-]suppress-from:: If this is set, do not add the From: address to the cc: list. - Default is the value of 'sendemail.suppressFrom' configuration + Default is the value of `sendemail.suppressFrom` configuration value; if that is unspecified, default to --no-suppress-from. --[no-]thread:: @@ -330,7 +330,7 @@ specified, as well as 'body' if --no-signed-off-cc is specified. + If disabled with "--no-thread", those headers will not be added (unless specified with --in-reply-to). Default is the value of the -'sendemail.thread' configuration value; if that is unspecified, +`sendemail.thread` configuration value; if that is unspecified, default to --thread. + It is up to the user to ensure that no In-Reply-To header already @@ -355,7 +355,7 @@ Administering - 'auto' is equivalent to 'cc' + 'compose' -- + -Default is the value of 'sendemail.confirm' configuration value; if that +Default is the value of `sendemail.confirm` configuration value; if that is unspecified, default to 'auto' unless any of the suppress options have been specified, in which case default to 'compose'. @@ -364,8 +364,8 @@ have been specified, in which case default to 'compose'. --[no-]format-patch:: When an argument may be understood either as a reference or as a file name, - choose to understand it as a format-patch argument ('--format-patch') - or as a file name ('--no-format-patch'). By default, when such a conflict + choose to understand it as a format-patch argument (`--format-patch`) + or as a file name (`--no-format-patch`). By default, when such a conflict occurs, git send-email will fail. --quiet:: @@ -381,8 +381,8 @@ have been specified, in which case default to 'compose'. is due to SMTP limits as described by http://www.ietf.org/rfc/rfc2821.txt. -- + -Default is the value of 'sendemail.validate'; if this is not set, -default to '--validate'. +Default is the value of `sendemail.validate`; if this is not set, +default to `--validate`. --force:: Send emails even if safety checks would prevent it. @@ -403,7 +403,7 @@ CONFIGURATION sendemail.aliasesFile:: To avoid typing long email addresses, point this to one or more - email aliases files. You must also supply 'sendemail.aliasFileType'. + email aliases files. You must also supply `sendemail.aliasFileType`. sendemail.aliasFileType:: Format of the file(s) specified in sendemail.aliasesFile. Must be @@ -428,13 +428,13 @@ sendmail;; sendemail.multiEdit:: If true (default), a single editor instance will be spawned to edit - files you have to edit (patches when '--annotate' is used, and the - summary when '--compose' is used). If false, files will be edited one + files you have to edit (patches when `--annotate` is used, and the + summary when `--compose` is used). If false, files will be edited one after the other, spawning a new editor each time. sendemail.confirm:: Sets the default for whether to confirm before sending. Must be - one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm' + one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm` in the previous section for the meaning of these values. EXAMPLE diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 6aa91e830c..a831dd0288 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -44,7 +44,7 @@ OPTIONS option, then the refs from stdin are processed after those on the command line. + -If '--stateless-rpc' is specified together with this option then +If `--stateless-rpc` is specified together with this option then the list of refs must be in packet format (pkt-line). Each ref must be in a separate packet, and the list must end with a flush packet. @@ -99,11 +99,11 @@ Specifying the Refs There are three ways to specify which refs to update on the remote end. -With '--all' flag, all refs that exist locally are transferred to +With `--all` flag, all refs that exist locally are transferred to the remote side. You cannot specify any '<ref>' if you use this flag. -Without '--all' and without any '<ref>', the heads that exist +Without `--all` and without any '<ref>', the heads that exist both on the local side and on the remote side are updated. When one or more '<ref>' are specified explicitly (whether on the @@ -134,13 +134,13 @@ name. See linkgit:git-rev-parse[1]. exist in the set of remote refs; the ref matched <src> locally is used as the name of the destination. -Without '--force', the <src> ref is stored at the remote only if +Without `--force`, the <src> ref is stored at the remote only if <dst> does not exist, or <dst> is a proper subset (i.e. an ancestor) of <src>. This check, known as "fast-forward check", is performed in order to avoid accidentally overwriting the remote ref and lose other peoples' commits from there. -With '--force', the fast-forward check is disabled for all refs. +With `--force`, the fast-forward check is disabled for all refs. Optionally, a <ref> parameter can be prefixed with a plus '+' sign to disable the fast-forward check only on that ref. diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 4f67c4cde6..8632612c31 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -41,7 +41,7 @@ usage:: die with the usage message. set_reflog_action:: - Set GIT_REFLOG_ACTION environment to a given string (typically + Set `GIT_REFLOG_ACTION` environment to a given string (typically the name of the program) unless it is already set. Whenever the script runs a `git` command that updates refs, a reflog entry is created using the value of this string to leave the diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index e4bdd2235c..2e30a3e42d 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -24,7 +24,7 @@ named `git-shell-commands` in the user's home directory. COMMANDS -------- -'git shell' accepts the following commands after the '-c' option: +'git shell' accepts the following commands after the `-c` option: 'git receive-pack <argument>':: 'git upload-pack <argument>':: @@ -43,7 +43,7 @@ directory. INTERACTIVE USE --------------- -By default, the commands above can be executed only with the '-c' +By default, the commands above can be executed only with the `-c` option; the shell is not interactive. If a `~/git-shell-commands` directory is present, 'git shell' diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index b91d4e545b..7818e0f098 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -60,7 +60,7 @@ OPTIONS are shown before their parents). --date-order:: - This option is similar to '--topo-order' in the sense that no + This option is similar to `--topo-order` in the sense that no parent comes before all of its children, but otherwise commits are ordered according to their commit date. diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index 3a32451984..c0aa871c9e 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -60,7 +60,7 @@ OPTIONS Enable stricter reference checking by requiring an exact ref path. Aside from returning an error code of 1, it will also print an error - message if '--quiet' was not specified. + message if `--quiet` was not specified. --abbrev[=<n>]:: @@ -70,7 +70,7 @@ OPTIONS -q:: --quiet:: - Do not print any results to stdout. When combined with '--verify' this + Do not print any results to stdout. When combined with `--verify` this can be used to silently check if a reference exists. --exclude-existing[=<pattern>]:: @@ -134,7 +134,7 @@ use: This will show "refs/heads/master" but also "refs/remote/other-repo/master", if such references exists. -When using the '--verify' flag, the command requires an exact path: +When using the `--verify` flag, the command requires an exact path: ----------------------------------------------------------------------------- git show-ref --verify refs/heads/master diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 9226c4380c..bf3bb372ee 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -15,8 +15,9 @@ SYNOPSIS 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...) 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] - [-f|--force] [--rebase|--merge] [--reference <repository>] - [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...] + [--[no-]recommend-shallow] [-f|--force] [--rebase|--merge] + [--reference <repository>] [--depth <depth>] [--recursive] + [--jobs <n>] [--] [<path>...] 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> @@ -384,6 +385,12 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully. clone with a history truncated to the specified number of revisions. See linkgit:git-clone[1] +--[no-]recommend-shallow:: + This option is only valid for the update command. + The initial clone of a submodule will use the recommended + `submodule.<name>.shallow` as provided by the .gitmodules file + by default. To ignore the suggestions use `--no-recommend-shallow`. + -j <n>:: --jobs <n>:: This option is only valid for the update command. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index fb23a98a17..7e17cade7f 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -98,11 +98,11 @@ your Perl's Getopt::Long is < v2.37). --ignore-paths=<regex>;; When passed to 'init' or 'clone' this regular expression will be preserved as a config key. See 'fetch' for a description - of '--ignore-paths'. + of `--ignore-paths`. --include-paths=<regex>;; When passed to 'init' or 'clone' this regular expression will be preserved as a config key. See 'fetch' for a description - of '--include-paths'. + of `--include-paths`. --no-minimize-url;; When tracking multiple directories (using --stdlayout, --branches, or --tags options), git svn will attempt to connect @@ -110,7 +110,7 @@ your Perl's Getopt::Long is < v2.37). repository. This default allows better tracking of history if entire projects are moved within a repository, but may cause issues on repositories where read access restrictions are in - place. Passing '--no-minimize-url' will allow git svn to + place. Passing `--no-minimize-url` will allow git svn to accept URLs as-is without attempting to connect to a higher level directory. This option is off by default when only one URL/branch is tracked (it would do little good). @@ -141,7 +141,7 @@ the same local time zone. --ignore-paths=<regex>;; This allows one to specify a Perl regular expression that will cause skipping of all matching paths from checkout from SVN. - The '--ignore-paths' option should match for every 'fetch' + The `--ignore-paths` option should match for every 'fetch' (including automatic fetches due to 'clone', 'dcommit', 'rebase', etc) on a given repository. + @@ -170,10 +170,10 @@ Skip "branches" and "tags" of first level directories;; --include-paths=<regex>;; This allows one to specify a Perl regular expression that will cause the inclusion of only matching paths from checkout from SVN. - The '--include-paths' option should match for every 'fetch' + The `--include-paths` option should match for every 'fetch' (including automatic fetches due to 'clone', 'dcommit', - 'rebase', etc) on a given repository. '--ignore-paths' takes - precedence over '--include-paths'. + 'rebase', etc) on a given repository. `--ignore-paths` takes + precedence over `--include-paths`. + [verse] config key: svn-remote.<name>.include-paths @@ -191,7 +191,7 @@ config key: svn-remote.<name>.include-paths or if a second argument is passed; it will create a directory and work within that. It accepts all arguments that the 'init' and 'fetch' commands accept; with the exception of - '--fetch-all' and '--parent'. After a repository is cloned, + `--fetch-all` and `--parent`. After a repository is cloned, the 'fetch' command will be able to update revisions without affecting the working tree; and the 'rebase' command will be able to update the working tree with the latest changes. @@ -216,7 +216,7 @@ it preserves linear history with 'git rebase' instead of 'git merge' for ease of dcommitting with 'git svn'. + This accepts all options that 'git svn fetch' and 'git rebase' -accept. However, '--fetch-all' only fetches from the current +accept. However, `--fetch-all` only fetches from the current [svn-remote], and not all [svn-remote] definitions. + Like 'git rebase'; this requires that the working tree be clean @@ -459,6 +459,20 @@ Any other arguments are passed directly to 'git log' Gets the Subversion property given as the first argument, for a file. A specific revision can be specified with -r/--revision. +'propset':: + Sets the Subversion property given as the first argument, to the + value given as the second argument for the file given as the + third argument. ++ +Example: ++ +------------------------------------------------------------------------ +git svn propset svn:keywords "FreeBSD=%H" devel/py-tipper/Makefile +------------------------------------------------------------------------ ++ +This will set the property 'svn:keywords' to 'FreeBSD=%H' for the file +'devel/py-tipper/Makefile'. + 'show-externals':: Shows the Subversion externals. Use -r/--revision to specify a specific revision. @@ -748,7 +762,7 @@ svn-remote.<name>.rewriteUUID:: svn-remote.<name>.pushurl:: - Similar to Git's 'remote.<name>.pushurl', this key is designed + Similar to Git's `remote.<name>.pushurl`, this key is designed to be used in cases where 'url' points to an SVN repository via a read-only transport, to provide an alternate read/write transport. It is assumed that both keys point to the same @@ -905,7 +919,7 @@ parent of the branch. However, it is possible that there is no suitable Git commit to serve as parent. This will happen, among other reasons, if the SVN branch is a copy of a revision that was not fetched by 'git svn' (e.g. because it is an old revision that was skipped with -'--revision'), or if in SVN a directory was copied that is not tracked +`--revision`), or if in SVN a directory was copied that is not tracked by 'git svn' (such as a branch that is not tracked at all, or a subdirectory of a tracked branch). In these cases, 'git svn' will still create a Git branch, but instead of using an existing Git commit as the @@ -982,12 +996,12 @@ directories in the working copy. While this is the easiest way to get a copy of a complete repository, for projects with many branches it will lead to a working copy many times larger than just the trunk. Thus for projects using the standard directory structure (trunk/branches/tags), -it is recommended to clone with option '--stdlayout'. If the project +it is recommended to clone with option `--stdlayout`. If the project uses a non-standard structure, and/or if branches and tags are not required, it is easiest to only clone one directory (typically trunk), without giving any repository layout options. If the full history with -branches and tags is required, the options '--trunk' / '--branches' / -'--tags' must be used. +branches and tags is required, the options `--trunk` / `--branches` / +`--tags` must be used. When using multiple --branches or --tags, 'git svn' does not automatically handle name collisions (for example, if two branches from different paths have diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index abab4814ec..7ecca8e247 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -78,7 +78,7 @@ OPTIONS -v:: --verify:: - Verify the gpg signature of the given tag names. + Verify the GPG signature of the given tag names. -n<num>:: <num> specifies how many lines from the annotation, if any, @@ -104,7 +104,7 @@ OPTIONS order can also be affected by the "versionsort.prereleaseSuffix" configuration variable. The keys supported are the same as those in `git for-each-ref`. - Sort order defaults to the value configured for the 'tag.sort' + Sort order defaults to the value configured for the `tag.sort` variable if it exists, or lexicographic order otherwise. See linkgit:git-config[1]. @@ -167,7 +167,7 @@ This option is only applicable when listing tags without annotation lines. --[no-]merged [<commit>]:: Only list tags whose tips are reachable, or not reachable - if '--no-merged' is used, from the specified commit ('HEAD' + if `--no-merged` is used, from the specified commit (`HEAD` if not specified). CONFIGURATION diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index c6cbed189c..7386c93162 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -102,7 +102,7 @@ thus, in case the assumed-untracked file is changed upstream, you will need to handle the situation manually. --really-refresh:: - Like '--refresh', but checks stat information unconditionally, + Like `--refresh`, but checks stat information unconditionally, without regard to the "assume unchanged" setting. --[no-]skip-worktree:: @@ -211,7 +211,7 @@ will remove the intended effect of the option. Using --refresh --------------- -'--refresh' does not calculate a new sha1 file or bring the index +`--refresh` does not calculate a new sha1 file or bring the index up-to-date for mode/content changes. But what it *does* do is to "re-match" the stat information of a file with the index, so that you can refresh the index for a file that hasn't been changed but where @@ -222,7 +222,7 @@ up the stat index details with the proper files. Using --cacheinfo or --info-only -------------------------------- -'--cacheinfo' is used to register a file that is not in the +`--cacheinfo` is used to register a file that is not in the current working directory. This is useful for minimum-checkout merging. @@ -232,12 +232,12 @@ To pretend you have a file with mode and sha1 at path, say: $ git update-index --cacheinfo <mode>,<sha1>,<path> ---------------- -'--info-only' is used to register files without placing them in the object +`--info-only` is used to register files without placing them in the object database. This is useful for status-only repositories. -Both '--cacheinfo' and '--info-only' behave similarly: the index is updated -but the object database isn't. '--cacheinfo' is useful when the object is -in the database but the file isn't available locally. '--info-only' is +Both `--cacheinfo` and `--info-only` behave similarly: the index is updated +but the object database isn't. `--cacheinfo` is useful when the object is +in the database but the file isn't available locally. `--info-only` is useful when the file is available, but you do not wish to update the object database. diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 0abc806ea9..822ad593af 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -9,8 +9,8 @@ git-upload-pack - Send objects packed back to git-fetch-pack SYNOPSIS -------- [verse] -'git-upload-pack' [--strict] [--timeout=<n>] <directory> - +'git-upload-pack' [--[no-]strict] [--timeout=<n>] [--stateless-rpc] + [--advertise-refs] <directory> DESCRIPTION ----------- Invoked by 'git fetch-pack', learns what @@ -25,12 +25,22 @@ repository. For push operations, see 'git send-pack'. OPTIONS ------- ---strict:: +--[no-]strict:: Do not try <directory>/.git/ if <directory> is no Git directory. --timeout=<n>:: Interrupt transfer after <n> seconds of inactivity. +--stateless-rpc:: + Perform only a single read-write cycle with stdin and stdout. + This fits with the HTTP POST request processing model where + a program may read the request, write a response, and must exit. + +--advertise-refs:: + Only the initial ref advertisement is output, and the program exits + immediately. This fits with the HTTP GET request model, where + no request content is received but a response must be produced. + <directory>:: The repository to sync from. diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt index ecf4da16cf..92097f6673 100644 --- a/Documentation/git-verify-commit.txt +++ b/Documentation/git-verify-commit.txt @@ -12,7 +12,7 @@ SYNOPSIS DESCRIPTION ----------- -Validates the gpg signature created by 'git commit -S'. +Validates the GPG signature created by 'git commit -S'. OPTIONS ------- diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index 16ede5b4c3..2d6b09a43c 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -62,14 +62,14 @@ CONF.VAR (from -c option) and web.browser ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The web browser can be specified using a configuration variable passed -with the -c (or --config) command-line option, or the 'web.browser' +with the -c (or --config) command-line option, or the `web.browser` configuration variable if the former is not used. browser.<tool>.path ~~~~~~~~~~~~~~~~~~~ You can explicitly provide a full path to your preferred browser by -setting the configuration variable 'browser.<tool>.path'. For example, +setting the configuration variable `browser.<tool>.path`. For example, you can configure the absolute path to firefox by setting 'browser.firefox.path'. Otherwise, 'git web{litdd}browse' assumes the tool is available in PATH. @@ -79,7 +79,7 @@ browser.<tool>.cmd When the browser, specified by options or configuration variables, is not among the supported ones, then the corresponding -'browser.<tool>.cmd' configuration variable will be looked up. If this +`browser.<tool>.cmd` configuration variable will be looked up. If this variable exists then 'git web{litdd}browse' will treat the specified tool as a custom command and will use a shell eval to run the command with the URLs passed as arguments. @@ -110,7 +110,7 @@ Note about git-config --global ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Note that these configuration variables should probably be set using -the '--global' flag, for example like this: +the `--global` flag, for example like this: ------------------------------------------------ $ git config --global web.browser firefox diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index c62234538b..7c4cfb0885 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -10,8 +10,8 @@ SYNOPSIS -------- [verse] 'git worktree add' [-f] [--detach] [--checkout] [-b <new-branch>] <path> [<branch>] -'git worktree prune' [-n] [-v] [--expire <expire>] 'git worktree list' [--porcelain] +'git worktree prune' [-n] [-v] [--expire <expire>] DESCRIPTION ----------- @@ -48,16 +48,13 @@ add <path> [<branch>]:: Create `<path>` and checkout `<branch>` into it. The new working directory is linked to the current repository, sharing everything except working -directory specific files such as HEAD, index, etc. +directory specific files such as HEAD, index, etc. `-` may also be +specified as `<branch>`; it is synonymous with `@{-1}`. + If `<branch>` is omitted and neither `-b` nor `-B` nor `--detached` used, then, as a convenience, a new branch based at HEAD is created automatically, as if `-b $(basename <path>)` was specified. -prune:: - -Prune working tree information in $GIT_DIR/worktrees. - list:: List details of each worktree. The main worktree is listed first, followed by @@ -65,6 +62,10 @@ each of the linked worktrees. The output details include if the worktree is bare, the revision currently checked out, and the branch currently checked out (or 'detached HEAD' if none). +prune:: + +Prune working tree information in $GIT_DIR/worktrees. + OPTIONS ------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 5490d3c601..f4dfc9d42c 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -31,8 +31,8 @@ page to learn what commands Git offers. You can learn more about individual Git commands with "git help command". linkgit:gitcli[7] manual page gives you an overview of the command-line command syntax. -Formatted and hyperlinked version of the latest Git documentation -can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`. +A formatted and hyperlinked copy of the latest Git documentation +can be viewed at `https://git.github.io/htmldocs/git.html`. ifdef::stalenotes[] [NOTE] @@ -43,9 +43,11 @@ unreleased) version of Git, that is available from the 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v2.9.0/git.html[documentation for release 2.9] +* link:v2.9.2/git.html[documentation for release 2.9.2] * release notes for + link:RelNotes/2.9.2.txt[2.9.2], + link:RelNotes/2.9.1.txt[2.9.1], link:RelNotes/2.9.0.txt[2.9]. * link:v2.8.4/git.html[documentation for release 2.8.4] @@ -513,7 +515,7 @@ OPTIONS --help:: Prints the synopsis and a list of the most commonly used - commands. If the option '--all' or '-a' is given then all + commands. If the option `--all` or `-a` is given then all available commands are printed. If a Git command is named this option will bring up the manual page for that command. + @@ -577,7 +579,7 @@ foo.bar= ...`) sets `foo.bar` to the empty string. --git-dir=<path>:: Set the path to the repository. This can also be controlled by - setting the GIT_DIR environment variable. It can be an absolute + setting the `GIT_DIR` environment variable. It can be an absolute path or relative path to current working directory. --work-tree=<path>:: @@ -827,46 +829,46 @@ These environment variables apply to 'all' core Git commands. Nb: it is worth noting that they may be used/overridden by SCMS sitting above Git so take care if using a foreign front-end. -'GIT_INDEX_FILE':: +`GIT_INDEX_FILE`:: This environment allows the specification of an alternate index file. If not specified, the default of `$GIT_DIR/index` is used. -'GIT_INDEX_VERSION':: +`GIT_INDEX_VERSION`:: This environment variable allows the specification of an index version for new repositories. It won't affect existing index files. By default index file version 2 or 3 is used. See linkgit:git-update-index[1] for more information. -'GIT_OBJECT_DIRECTORY':: +`GIT_OBJECT_DIRECTORY`:: If the object storage directory is specified via this environment variable then the sha1 directories are created underneath - otherwise the default `$GIT_DIR/objects` directory is used. -'GIT_ALTERNATE_OBJECT_DIRECTORIES':: +`GIT_ALTERNATE_OBJECT_DIRECTORIES`:: Due to the immutable nature of Git objects, old objects can be archived into shared, read-only directories. This variable specifies a ":" separated (on Windows ";" separated) list of Git object directories which can be used to search for Git objects. New objects will not be written to these directories. -'GIT_DIR':: - If the 'GIT_DIR' environment variable is set then it +`GIT_DIR`:: + If the `GIT_DIR` environment variable is set then it specifies a path to use instead of the default `.git` for the base of the repository. - The '--git-dir' command-line option also sets this value. + The `--git-dir` command-line option also sets this value. -'GIT_WORK_TREE':: +`GIT_WORK_TREE`:: Set the path to the root of the working tree. - This can also be controlled by the '--work-tree' command-line + This can also be controlled by the `--work-tree` command-line option and the core.worktree configuration variable. -'GIT_NAMESPACE':: +`GIT_NAMESPACE`:: Set the Git namespace; see linkgit:gitnamespaces[7] for details. - The '--namespace' command-line option also sets this value. + The `--namespace` command-line option also sets this value. -'GIT_CEILING_DIRECTORIES':: +`GIT_CEILING_DIRECTORIES`:: This should be a colon-separated list of absolute paths. If set, it is a list of directories that Git should not chdir up into while looking for a repository directory (useful for @@ -879,19 +881,19 @@ Git so take care if using a foreign front-end. can add an empty entry to the list to tell Git that the subsequent entries are not symlinks and needn't be resolved; e.g., - 'GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink'. + `GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink`. -'GIT_DISCOVERY_ACROSS_FILESYSTEM':: +`GIT_DISCOVERY_ACROSS_FILESYSTEM`:: When run in a directory that does not have ".git" repository directory, Git tries to find such a directory in the parent directories to find the top of the working tree, but by default it does not cross filesystem boundaries. This environment variable can be set to true to tell Git not to stop at filesystem - boundaries. Like 'GIT_CEILING_DIRECTORIES', this will not affect - an explicit repository directory set via 'GIT_DIR' or on the + boundaries. Like `GIT_CEILING_DIRECTORIES`, this will not affect + an explicit repository directory set via `GIT_DIR` or on the command line. -'GIT_COMMON_DIR':: +`GIT_COMMON_DIR`:: If this variable is set to a path, non-worktree files that are normally in $GIT_DIR will be taken from this path instead. Worktree-specific files such as HEAD or index are @@ -902,28 +904,28 @@ Git so take care if using a foreign front-end. Git Commits ~~~~~~~~~~~ -'GIT_AUTHOR_NAME':: -'GIT_AUTHOR_EMAIL':: -'GIT_AUTHOR_DATE':: -'GIT_COMMITTER_NAME':: -'GIT_COMMITTER_EMAIL':: -'GIT_COMMITTER_DATE':: +`GIT_AUTHOR_NAME`:: +`GIT_AUTHOR_EMAIL`:: +`GIT_AUTHOR_DATE`:: +`GIT_COMMITTER_NAME`:: +`GIT_COMMITTER_EMAIL`:: +`GIT_COMMITTER_DATE`:: 'EMAIL':: see linkgit:git-commit-tree[1] Git Diffs ~~~~~~~~~ -'GIT_DIFF_OPTS':: +`GIT_DIFF_OPTS`:: Only valid setting is "--unified=??" or "-u??" to set the number of context lines shown when a unified diff is created. This takes precedence over any "-U" or "--unified" option value passed on the Git diff command line. -'GIT_EXTERNAL_DIFF':: - When the environment variable 'GIT_EXTERNAL_DIFF' is set, the +`GIT_EXTERNAL_DIFF`:: + When the environment variable `GIT_EXTERNAL_DIFF` is set, the program named by it is called, instead of the diff invocation described above. For a path that is added, removed, or modified, - 'GIT_EXTERNAL_DIFF' is called with 7 parameters: + `GIT_EXTERNAL_DIFF` is called with 7 parameters: path old-file old-hex old-mode new-file new-hex new-mode + @@ -937,49 +939,49 @@ where: The file parameters can point at the user's working file (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` when a new file is added), or a temporary file (e.g. `old-file` in the -index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the -temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits. +index). `GIT_EXTERNAL_DIFF` should not worry about unlinking the +temporary file --- it is removed when `GIT_EXTERNAL_DIFF` exits. + -For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1 +For a path that is unmerged, `GIT_EXTERNAL_DIFF` is called with 1 parameter, <path>. + -For each path 'GIT_EXTERNAL_DIFF' is called, two environment variables, -'GIT_DIFF_PATH_COUNTER' and 'GIT_DIFF_PATH_TOTAL' are set. +For each path `GIT_EXTERNAL_DIFF` is called, two environment variables, +`GIT_DIFF_PATH_COUNTER` and `GIT_DIFF_PATH_TOTAL` are set. -'GIT_DIFF_PATH_COUNTER':: +`GIT_DIFF_PATH_COUNTER`:: A 1-based counter incremented by one for every path. -'GIT_DIFF_PATH_TOTAL':: +`GIT_DIFF_PATH_TOTAL`:: The total number of paths. other ~~~~~ -'GIT_MERGE_VERBOSITY':: +`GIT_MERGE_VERBOSITY`:: A number controlling the amount of output shown by the recursive merge strategy. Overrides merge.verbosity. See linkgit:git-merge[1] -'GIT_PAGER':: +`GIT_PAGER`:: This environment variable overrides `$PAGER`. If it is set to an empty string or to the value "cat", Git will not launch a pager. See also the `core.pager` option in linkgit:git-config[1]. -'GIT_EDITOR':: +`GIT_EDITOR`:: This environment variable overrides `$EDITOR` and `$VISUAL`. It is used by several Git commands when, on interactive mode, an editor is to be launched. See also linkgit:git-var[1] and the `core.editor` option in linkgit:git-config[1]. -'GIT_SSH':: -'GIT_SSH_COMMAND':: +`GIT_SSH`:: +`GIT_SSH_COMMAND`:: If either of these environment variables is set then 'git fetch' and 'git push' will use the specified command instead of 'ssh' when they need to connect to a remote system. The command will be given exactly two or four arguments: the 'username@host' (or just 'host') from the URL and the shell command to execute on that remote system, optionally preceded by - '-p' (literally) and the 'port' from the URL when it specifies + `-p` (literally) and the 'port' from the URL when it specifies something other than the default SSH port. + `$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted @@ -992,18 +994,18 @@ Usually it is easier to configure any desired options through your personal `.ssh/config` file. Please consult your ssh documentation for further details. -'GIT_ASKPASS':: +`GIT_ASKPASS`:: If this environment variable is set, then Git commands which need to acquire passwords or passphrases (e.g. for HTTP or IMAP authentication) will call this program with a suitable prompt as command-line argument - and read the password from its STDOUT. See also the 'core.askPass' + and read the password from its STDOUT. See also the `core.askPass` option in linkgit:git-config[1]. -'GIT_TERMINAL_PROMPT':: +`GIT_TERMINAL_PROMPT`:: If this environment variable is set to `0`, git will not prompt on the terminal (e.g., when asking for HTTP authentication). -'GIT_CONFIG_NOSYSTEM':: +`GIT_CONFIG_NOSYSTEM`:: Whether to skip reading settings from the system-wide `$(prefix)/etc/gitconfig` file. This environment variable can be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a @@ -1011,7 +1013,7 @@ for further details. temporarily to avoid using a buggy `/etc/gitconfig` file while waiting for someone with sufficient permissions to fix it. -'GIT_FLUSH':: +`GIT_FLUSH`:: If this environment variable is set to "1", then commands such as 'git blame' (in incremental mode), 'git rev-list', 'git log', 'git check-attr' and 'git check-ignore' will @@ -1022,7 +1024,7 @@ for further details. not set, Git will choose buffered or record-oriented flushing based on whether stdout appears to be redirected to a file or not. -'GIT_TRACE':: +`GIT_TRACE`:: Enables general trace messages, e.g. alias expansion, built-in command execution and external command execution. + @@ -1043,21 +1045,21 @@ into it. Unsetting the variable, or setting it to empty, "0" or "false" (case insensitive) disables trace messages. -'GIT_TRACE_PACK_ACCESS':: +`GIT_TRACE_PACK_ACCESS`:: Enables trace messages for all accesses to any packs. For each access, the pack file name and an offset in the pack is recorded. This may be helpful for troubleshooting some pack-related performance problems. - See 'GIT_TRACE' for available trace output options. + See `GIT_TRACE` for available trace output options. -'GIT_TRACE_PACKET':: +`GIT_TRACE_PACKET`:: Enables trace messages for all packets coming in or out of a given program. This can help with debugging object negotiation or other protocol issues. Tracing is turned off at a packet - starting with "PACK" (but see 'GIT_TRACE_PACKFILE' below). - See 'GIT_TRACE' for available trace output options. + starting with "PACK" (but see `GIT_TRACE_PACKFILE` below). + See `GIT_TRACE` for available trace output options. -'GIT_TRACE_PACKFILE':: +`GIT_TRACE_PACKFILE`:: Enables tracing of packfiles sent or received by a given program. Unlike other trace output, this trace is verbatim: no headers, and no quoting of binary data. You almost @@ -1068,22 +1070,30 @@ Unsetting the variable, or setting it to empty, "0" or Note that this is currently only implemented for the client side of clones and fetches. -'GIT_TRACE_PERFORMANCE':: +`GIT_TRACE_PERFORMANCE`:: Enables performance related trace messages, e.g. total execution time of each Git command. - See 'GIT_TRACE' for available trace output options. + See `GIT_TRACE` for available trace output options. -'GIT_TRACE_SETUP':: +`GIT_TRACE_SETUP`:: Enables trace messages printing the .git, working tree and current working directory after Git has completed its setup phase. - See 'GIT_TRACE' for available trace output options. + See `GIT_TRACE` for available trace output options. -'GIT_TRACE_SHALLOW':: +`GIT_TRACE_SHALLOW`:: Enables trace messages that can help debugging fetching / cloning of shallow repositories. - See 'GIT_TRACE' for available trace output options. + See `GIT_TRACE` for available trace output options. -'GIT_LITERAL_PATHSPECS':: +`GIT_TRACE_CURL`:: + Enables a curl full trace dump of all incoming and outgoing data, + including descriptive information, of the git transport protocol. + This is similar to doing curl `--trace-ascii` on the command line. + This option overrides setting the `GIT_CURL_VERBOSE` environment + variable. + See `GIT_TRACE` for available trace output options. + +`GIT_LITERAL_PATHSPECS`:: Setting this variable to `1` will cause Git to treat all pathspecs literally, rather than as glob patterns. For example, running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search @@ -1092,19 +1102,19 @@ of clones and fetches. literal paths to Git (e.g., paths previously given to you by `git ls-tree`, `--raw` diff output, etc). -'GIT_GLOB_PATHSPECS':: +`GIT_GLOB_PATHSPECS`:: Setting this variable to `1` will cause Git to treat all pathspecs as glob patterns (aka "glob" magic). -'GIT_NOGLOB_PATHSPECS':: +`GIT_NOGLOB_PATHSPECS`:: Setting this variable to `1` will cause Git to treat all pathspecs as literal (aka "literal" magic). -'GIT_ICASE_PATHSPECS':: +`GIT_ICASE_PATHSPECS`:: Setting this variable to `1` will cause Git to treat all pathspecs as case-insensitive. -'GIT_REFLOG_ACTION':: +`GIT_REFLOG_ACTION`:: When a ref is updated, reflog entries are created to keep track of the reason why the ref was updated (which is typically the name of the high-level command that updated @@ -1114,7 +1124,7 @@ of clones and fetches. variable when it is invoked as the top level command by the end user, to be recorded in the body of the reflog. -'GIT_REF_PARANOIA':: +`GIT_REF_PARANOIA`:: If set to `1`, include broken or badly named refs when iterating over lists of refs. In a normal, non-corrupted repository, this does nothing. However, enabling it may help git to detect and @@ -1125,7 +1135,7 @@ of clones and fetches. an operation has touched every ref (e.g., because you are cloning a repository to make a backup). -'GIT_ALLOW_PROTOCOL':: +`GIT_ALLOW_PROTOCOL`:: If set, provide a colon-separated list of protocols which are allowed to be used with fetch/push/clone. This is useful to restrict recursive submodule initialization from an untrusted diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index e3b1de8033..b40068bdfd 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -115,6 +115,7 @@ text file is normalized, its line endings are converted to LF in the repository. To control what line ending style is used in the working directory, use the `eol` attribute for a single file and the `core.eol` configuration variable for all text files. +Note that `core.autocrlf` overrides `core.eol` Set:: @@ -130,8 +131,9 @@ Unset:: Set to string value "auto":: When `text` is set to "auto", the path is marked for automatic - end-of-line normalization. If Git decides that the content is - text, its line endings are normalized to LF on checkin. + end-of-line conversion. If Git decides that the content is + text, its line endings are converted to LF on checkin. + When the file has been commited with CRLF, no conversion is done. Unspecified:: @@ -146,7 +148,7 @@ unspecified. ^^^^^ This attribute sets a specific line-ending style to be used in the -working directory. It enables end-of-line normalization without any +working directory. It enables end-of-line conversion without any content checks, effectively setting the `text` attribute. Set to string value "crlf":: @@ -186,9 +188,10 @@ the working directory, and prevent .jpg files from being normalized regardless of their content. ------------------------ +* text=auto *.txt text -*.vcproj eol=crlf -*.sh eol=lf +*.vcproj text eol=crlf +*.sh text eol=lf *.jpg -text ------------------------ @@ -198,7 +201,7 @@ normalization in Git. If you simply want to have CRLF line endings in your working directory regardless of the repository you are working with, you can set the -config variable "core.autocrlf" without changing any attributes. +config variable "core.autocrlf" without using any attributes. ------------------------ [core] @@ -525,6 +528,8 @@ patterns are available: - `csharp` suitable for source code in the C# language. +- `css` suitable for cascading style sheets. + - `fortran` suitable for source code in the Fortran language. - `fountain` suitable for Fountain documents. diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 15b3bfa8db..4546fa0d75 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -949,7 +949,7 @@ for details. [NOTE] If there were more commits on the 'master' branch after the merge, the merge commit itself would not be shown by 'git show-branch' by -default. You would need to provide '--sparse' option to make the +default. You would need to provide `--sparse` option to make the merge commit visible in this case. Now, let's pretend you are the one who did all the work in diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index c579593e55..08cf62278e 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -28,8 +28,8 @@ The 'git diff-{asterisk}' family works by first comparing two sets of files: - 'git diff-index' compares contents of a "tree" object and the - working directory (when '--cached' flag is not used) or a - "tree" object and the index file (when '--cached' flag is + working directory (when `--cached` flag is not used) or a + "tree" object and the index file (when `--cached` flag is used); - 'git diff-files' compares contents of the index file and the diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 473623d631..63260f0056 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -38,7 +38,7 @@ precedence, the last matching pattern decides the outcome): * Patterns read from `$GIT_DIR/info/exclude`. * Patterns read from the file specified by the configuration - variable 'core.excludesFile'. + variable `core.excludesFile`. Which file to place a pattern in depends on how the pattern is meant to be used. diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 6ade002176..a68d860fa3 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -82,7 +82,7 @@ linkgit:git-rev-list[1] for a complete list. --simplify-merges:: - Additional option to '--full-history' to remove some needless + Additional option to `--full-history` to remove some needless merges from the resulting history, as there are no selected commits contributing to this merge. (See "History simplification" in linkgit:git-log[1] for a more detailed diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index ac70eca321..07cdd73ab2 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -19,7 +19,7 @@ of linkgit:git-config[1]. The file contains one subsection per submodule, and the subsection value is the name of the submodule. The name is set to the path where the -submodule has been added unless it was customized with the '--name' +submodule has been added unless it was customized with the `--name` option of 'git submodule add'. Each submodule section also contains the following required keys: diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 78e0b27c18..a4de50ad22 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -43,7 +43,7 @@ arguments. The first argument specifies a remote repository as in Git; it is either the name of a configured remote or a URL. The second argument specifies a URL; it is usually of the form '<transport>://<address>', but any arbitrary string is possible. -The 'GIT_DIR' environment variable is set up for the remote helper +The `GIT_DIR` environment variable is set up for the remote helper and can be used to determine where to store additional data or from which directory to invoke auxiliary Git commands. @@ -61,10 +61,10 @@ argument. If such a URL is encountered directly on the command line, the first argument is '<address>', and if it is encountered in a configured remote, the first argument is the name of that remote. -Additionally, when a configured remote has 'remote.<name>.vcs' set to +Additionally, when a configured remote has `remote.<name>.vcs` set to '<transport>', Git explicitly invokes 'git remote-<transport>' with '<name>' as the first argument. If set, the second argument is -'remote.<name>.url'; otherwise, the second argument is omitted. +`remote.<name>.url`; otherwise, the second argument is omitted. INPUT FORMAT ------------ @@ -210,17 +210,17 @@ the remote repository. 'export-marks' <file>:: This modifies the 'export' capability, instructing Git to dump the internal marks table to <file> when complete. For details, - read up on '--export-marks=<file>' in linkgit:git-fast-export[1]. + read up on `--export-marks=<file>` in linkgit:git-fast-export[1]. 'import-marks' <file>:: This modifies the 'export' capability, instructing Git to load the marks specified in <file> before processing any input. For details, - read up on '--import-marks=<file>' in linkgit:git-fast-export[1]. + read up on `--import-marks=<file>` in linkgit:git-fast-export[1]. 'signed-tags':: This modifies the 'export' capability, instructing Git to pass - '--signed-tags=verbatim' to linkgit:git-fast-export[1]. In the - absence of this capability, Git will use '--signed-tags=warn-strip'. + `--signed-tags=verbatim` to linkgit:git-fast-export[1]. In the + absence of this capability, Git will use `--signed-tags=warn-strip`. @@ -298,7 +298,7 @@ Supported if the helper has the "fetch" capability. is followed by a blank line). For example, the following would be two batches of 'push', the first asking the remote-helper to push the local ref 'master' to the remote ref 'master' and - the local 'HEAD' to the remote 'branch', and the second + the local `HEAD` to the remote 'branch', and the second asking to push ref 'foo' to ref 'bar' (forced update requested by the '+'). + diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index 8a42270074..a79e350246 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -376,7 +376,7 @@ $site_name:: Name of your site or organization, to appear in page titles. Set it to something descriptive for clearer bookmarks etc. If this variable is not set or is, then gitweb uses the value of the `SERVER_NAME` - CGI environment variable, setting site name to "$SERVER_NAME Git", + `CGI` environment variable, setting site name to "$SERVER_NAME Git", or "Untitled Git" if this variable is not set (e.g. if running gitweb as standalone script). + diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt index cd9c8951b2..96156e5e1f 100644 --- a/Documentation/gitweb.txt +++ b/Documentation/gitweb.txt @@ -206,8 +206,8 @@ $export_auth_hook = sub { Per-repository gitweb configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can configure individual repositories shown in gitweb by creating file -in the 'GIT_DIR' of Git repository, or by setting some repo configuration -variable (in 'GIT_DIR/config', see linkgit:git-config[1]). +in the `GIT_DIR` of Git repository, or by setting some repo configuration +variable (in `GIT_DIR/config`, see linkgit:git-config[1]). You can use the following files in repository: diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt index 6d772bd927..15a4c8031f 100644 --- a/Documentation/howto/new-command.txt +++ b/Documentation/howto/new-command.txt @@ -94,7 +94,7 @@ your language, document it in the INSTALL file. 6. There is a file command-list.txt in the distribution main directory that categorizes commands by type, so they can be listed in appropriate subsections in the documentation's summary command list. Add an entry -for yours. To understand the categories, look at git-commands.txt +for yours. To understand the categories, look at command-list.txt in the main directory. If the new command is part of the typical Git workflow and you believe it common enough to be mentioned in 'git help', map this command to a common group in the column [common]. diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index 002ca58c21..df3ea3779b 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -61,7 +61,7 @@ merge.verbosity:: message if conflicts were detected. Level 1 outputs only conflicts, 2 outputs conflicts and file changes. Level 5 and 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:: Defines a human-readable name for a custom low-level diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 6c67182728..e44fc8f738 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -26,7 +26,7 @@ people using 80-column terminals. --no-abbrev-commit:: Show the full 40-byte hexadecimal commit object name. This negates `--abbrev-commit` and those options which imply it such as - "--oneline". It also overrides the 'log.abbrevCommit' variable. + "--oneline". It also overrides the `log.abbrevCommit` variable. --oneline:: This is a shorthand for "--pretty=oneline --abbrev-commit" @@ -65,7 +65,7 @@ ifndef::git-rev-list[] on the command line. + By default, the notes shown are from the notes refs listed in the -'core.notesRef' and 'notes.displayRef' variables (or corresponding +`core.notesRef` and `notes.displayRef` variables (or corresponding environment overrides). See linkgit:git-config[1] for more details. + With an optional '<treeish>' argument, use the treeish to find the notes diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 4f009d4424..c5bd21812d 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -193,7 +193,7 @@ endif::git-rev-list[] --stdin:: In addition to the '<commit>' listed on the command - line, read them from the standard input. If a '--' separator is + line, read them from the standard input. If a `--` separator is seen, stop reading commits and start reading paths to limit the result. diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 19314e3b7f..abae363983 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -28,8 +28,8 @@ blobs contained in a commit. first match in the following rules: . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually - useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD' - and 'CHERRY_PICK_HEAD'); + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD` + and `CHERRY_PICK_HEAD`); . otherwise, 'refs/<refname>' if it exists; @@ -41,16 +41,16 @@ blobs contained in a commit. . otherwise, 'refs/remotes/<refname>/HEAD' if it exists. + -'HEAD' names the commit on which you based the changes in the working tree. -'FETCH_HEAD' records the branch which you fetched from a remote repository +`HEAD` names the commit on which you based the changes in the working tree. +`FETCH_HEAD` records the branch which you fetched from a remote repository with your last `git fetch` invocation. -'ORIG_HEAD' is created by commands that move your 'HEAD' in a drastic -way, to record the position of the 'HEAD' before their operation, so that +`ORIG_HEAD` is created by commands that move your `HEAD` in a drastic +way, to record the position of the `HEAD` before their operation, so that you can easily change the tip of the branch back to the state before you ran them. -'MERGE_HEAD' records the commit(s) which you are merging into your branch +`MERGE_HEAD` records the commit(s) which you are merging into your branch when you run `git merge`. -'CHERRY_PICK_HEAD' records the commit which you are cherry-picking +`CHERRY_PICK_HEAD` records the commit which you are cherry-picking when you run `git cherry-pick`. + Note that any of the 'refs/*' cases above may come either from @@ -59,7 +59,7 @@ While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8. '@':: - '@' alone is a shortcut for 'HEAD'. + '@' alone is a shortcut for `HEAD`. '<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}':: A ref followed by the suffix '@' with a date specification @@ -71,7 +71,7 @@ some output processing may assume ref names in UTF-8. existing log ('$GIT_DIR/logs/<ref>'). Note that this looks up the state of your *local* ref at a given time; e.g., what was in your local 'master' branch last week. If you want to look at commits made during - certain times, see '--since' and '--until'. + certain times, see `--since` and `--until`. '<refname>@{<n>}', e.g. 'master@\{1\}':: A ref followed by the suffix '@' with an ordinal specification @@ -101,7 +101,7 @@ some output processing may assume ref names in UTF-8. '<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: The suffix '@\{push}' reports the branch "where we would push to" if `git push` were run while `branchname` was checked out (or the current - 'HEAD' if no branchname is specified). Since our push destination is + `HEAD` if no branchname is specified). Since our push destination is in a remote repository, of course, we report the local tracking branch that corresponds to that branch (i.e., something in 'refs/remotes/'). + @@ -283,12 +283,12 @@ To summarize: '<rev1>..<rev2>':: Include commits that are reachable from <rev2> but exclude those that are reachable from <rev1>. When either <rev1> or - <rev2> is omitted, it defaults to 'HEAD'. + <rev2> is omitted, it defaults to `HEAD`. '<rev1>\...<rev2>':: Include commits that are reachable from either <rev1> or <rev2> but exclude those that are reachable from both. When - either <rev1> or <rev2> is omitted, it defaults to 'HEAD'. + either <rev1> or <rev2> is omitted, it defaults to `HEAD`. '<rev>{caret}@', e.g. 'HEAD{caret}@':: A suffix '{caret}' followed by an at sign is the same as listing diff --git a/Documentation/technical/signature-format.txt b/Documentation/technical/signature-format.txt new file mode 100644 index 0000000000..2c9406a56a --- /dev/null +++ b/Documentation/technical/signature-format.txt @@ -0,0 +1,186 @@ +Git signature format +==================== + +== Overview + +Git uses cryptographic signatures in various places, currently objects (tags, +commits, mergetags) and transactions (pushes). In every case, the command which +is about to create an object or transaction determines a payload from that, +calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and +embeds the signature into the object or transaction. + +Signatures always begin with `-----BEGIN PGP SIGNATURE-----` +and end with `-----END PGP SIGNATURE-----`, unless gpg is told to +produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`. + +The signed payload and the way the signature is embedded depends +on the type of the object resp. transaction. + +== Tag signatures + +- created by: `git tag -s` +- payload: annotated tag object +- embedding: append the signature to the unsigned tag object +- example: tag `signedtag` with subject `signed tag` + +---- +object 04b871796dc0420f8e7561a895b52484b701d51a +type commit +tag signedtag +tagger C O Mitter <committer@example.com> 1465981006 +0000 + +signed tag + +signed tag message body +-----BEGIN PGP SIGNATURE----- +Version: GnuPG v1 + +iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn +rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh +8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods +q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0 +rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x +lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E= +=jpXa +-----END PGP SIGNATURE----- +---- + +- verify with: `git verify-tag [-v]` or `git tag -v` + +---- +gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189 +gpg: Good signature from "Eris Discordia <discord@example.net>" +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +object 04b871796dc0420f8e7561a895b52484b701d51a +type commit +tag signedtag +tagger C O Mitter <committer@example.com> 1465981006 +0000 + +signed tag + +signed tag message body +---- + +== Commit signatures + +- created by: `git commit -S` +- payload: commit object +- embedding: header entry `gpgsig` + (content is preceded by a space) +- example: commit with subject `signed commit` + +---- +tree eebfed94e75e7760540d1485c740902590a00332 +parent 04b871796dc0420f8e7561a895b52484b701d51a +author A U Thor <author@example.com> 1465981137 +0000 +committer C O Mitter <committer@example.com> 1465981137 +0000 +gpgsig -----BEGIN PGP SIGNATURE----- + Version: GnuPG v1 + + iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/ + HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7 + DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA + zn075rtEERDHr8nRYiDh8eVrefSO7D+bdQ7gv+7GsYMsd2auJWi1dHOSfTr9HIF4 + HJhWXT9d2f8W+diRYXGh4X0wYiGg6na/soXc+vdtDYBzIxanRqjg8jCAeo1eOTk1 + EdTwhcTZlI0x5pvJ3H0+4hA2jtldVtmPM4OTB0cTrEWBad7XV6YgiyuII73Ve3I= + =jKHM + -----END PGP SIGNATURE----- + +signed commit + +signed commit message body +---- + +- verify with: `git verify-commit [-v]` (or `git show --show-signature`) + +---- +gpg: Signature made Wed Jun 15 10:58:57 2016 CEST using RSA key ID B7227189 +gpg: Good signature from "Eris Discordia <discord@example.net>" +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +tree eebfed94e75e7760540d1485c740902590a00332 +parent 04b871796dc0420f8e7561a895b52484b701d51a +author A U Thor <author@example.com> 1465981137 +0000 +committer C O Mitter <committer@example.com> 1465981137 +0000 + +signed commit + +signed commit message body +---- + +== Mergetag signatures + +- created by: `git merge` on signed tag +- payload/embedding: the whole signed tag object is embedded into + the (merge) commit object as header entry `mergetag` +- example: merge of the signed tag `signedtag` as above + +---- +tree c7b1cff039a93f3600a1d18b82d26688668c7dea +parent c33429be94b5f2d3ee9b0adad223f877f174b05d +parent 04b871796dc0420f8e7561a895b52484b701d51a +author A U Thor <author@example.com> 1465982009 +0000 +committer C O Mitter <committer@example.com> 1465982009 +0000 +mergetag object 04b871796dc0420f8e7561a895b52484b701d51a + type commit + tag signedtag + tagger C O Mitter <committer@example.com> 1465981006 +0000 + + signed tag + + signed tag message body + -----BEGIN PGP SIGNATURE----- + Version: GnuPG v1 + + iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn + rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh + 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods + q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0 + rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x + lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E= + =jpXa + -----END PGP SIGNATURE----- + +Merge tag 'signedtag' into downstream + +signed tag + +signed tag message body + +# gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189 +# gpg: Good signature from "Eris Discordia <discord@example.net>" +# gpg: WARNING: This key is not certified with a trusted signature! +# gpg: There is no indication that the signature belongs to the owner. +# Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +---- + +- verify with: verification is embedded in merge commit message by default, + alternatively with `git show --show-signature`: + +---- +commit 9863f0c76ff78712b6800e199a46aa56afbcbd49 +merged tag 'signedtag' +gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189 +gpg: Good signature from "Eris Discordia <discord@example.net>" +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +Merge: c33429b 04b8717 +Author: A U Thor <author@example.com> +Date: Wed Jun 15 09:13:29 2016 +0000 + + Merge tag 'signedtag' into downstream + + signed tag + + signed tag message body + + # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189 + # gpg: Good signature from "Eris Discordia <discord@example.net>" + # gpg: WARNING: This key is not certified with a trusted signature! + # gpg: There is no indication that the signature belongs to the owner. + # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189 +---- |