diff options
Diffstat (limited to 'Documentation')
44 files changed, 1036 insertions, 211 deletions
diff --git a/Documentation/RelNotes/2.12.0.txt b/Documentation/RelNotes/2.12.0.txt index 0c6eed2007..29154805b4 100644 --- a/Documentation/RelNotes/2.12.0.txt +++ b/Documentation/RelNotes/2.12.0.txt @@ -131,6 +131,9 @@ UI, Workflows & Features other than the ones that are expected to be updated (i.e. branches, remote-tracking branches and notes). + * Comes with more command line completion (in contrib/) for recently + introduced options. + Performance, Internal Implementation, Development Support etc. @@ -436,6 +439,45 @@ notes for details). with AsciiDoc. "make USE_ASCIIDOCTOR=YesPlease" to use it out of the box to document our pages is getting closer to reality. + * Correct command line completion (in contrib/) on "git svn" + (merge 2cbad17642 ew/complete-svn-authorship-options later to maint). + + * Incorrect usage help message for "git worktree prune" has been fixed. + (merge 2488dcab22 ps/worktree-prune-help-fix later to maint). + + * Adjust a perf test to new world order where commands that do + require a repository are really strict about having a repository. + (merge c86000c1a7 rs/p5302-create-repositories-before-tests later to maint). + + * "git log --graph" did not work well with "--name-only", even though + other forms of "diff" output were handled correctly. + (merge f5022b5fed jk/log-graph-name-only later to maint). + + * The push-options given via the "--push-options" option were not + passed through to external remote helpers such as "smart HTTP" that + are invoked via the transport helper. + + * The documentation explained what "git stash" does to the working + tree (after stashing away the local changes) in terms of "reset + --hard", which was exposing an unnecessary implementation detail. + (merge 20a7e06172 tg/stash-doc-cleanup later to maint). + + * When "git p4" imports changelist that removes paths, it failed to + convert pathnames when the p4 used encoding different from the one + used on the Git side. This has been corrected. + (merge a8b05162e8 ls/p4-path-encoding later to maint). + + * A new coccinelle rule that catches a check of !pointer before the + pointer is free(3)d, which most likely is a bug. + (merge ec6cd14c7a rs/cocci-check-free-only-null later to maint). + + * "ls-files" run with pathspec has been micro-optimized to avoid + having to memmove(3) unnecessary bytes. + (merge 96f6d3f61a rs/ls-files-partial-optim later to maint). + + * A hotfix for a topic already in 'master'. + (merge a4d92d579f js/mingw-isatty later to maint). + * Other minor doc, test and build updates and code cleanups. (merge f2627d9b19 sb/submodule-config-cleanup later to maint). (merge 384f1a167b sb/unpack-trees-cleanup later to maint). @@ -444,3 +486,15 @@ notes for details). (merge 0aaad415bc rs/absolute-pathdup later to maint). (merge 4432dd6b5b rs/receive-pack-cleanup later to maint). (merge 540a398e9c sg/mailmap-self later to maint). + (merge 209df269a6 nd/rev-list-all-includes-HEAD-doc later to maint). + (merge 941b9c5270 sb/doc-unify-bottom later to maint). + (merge 2aaf37b62c jk/doc-remote-helpers-markup-fix later to maint). + (merge e91461b332 jk/doc-submodule-markup-fix later to maint). + (merge 8ab9740d9f dp/submodule-doc-markup-fix later to maint). + (merge 0838cbc22f jk/tempfile-ferror-fclose-confusion later to maint). + (merge 115a40add6 dr/doc-check-ref-format-normalize later to maint). + (merge 133f0a299d gp/document-dotfiles-in-templates-are-not-copied later to maint). + (merge 2b35a9f4c7 bc/blame-doc-fix later to maint). + (merge 7e82388024 ps/doc-gc-aggressive-depth-update later to maint). + (merge 9993a7c5f1 bc/worktree-doc-fix-detached later to maint). + (merge e519eccdf4 rt/align-add-i-help-text later to maint). diff --git a/Documentation/RelNotes/2.12.1.txt b/Documentation/RelNotes/2.12.1.txt new file mode 100644 index 0000000000..a74f7db747 --- /dev/null +++ b/Documentation/RelNotes/2.12.1.txt @@ -0,0 +1,41 @@ +Git v2.12.1 Release Notes +========================= + +Fixes since v2.12 +----------------- + + * Reduce authentication round-trip over HTTP when the server supports + just a single authentication method. This also improves the + behaviour when Git is misconfigured to enable http.emptyAuth + against a server that does not authenticate without a username + (i.e. not using Kerberos etc., which makes http.emptyAuth + pointless). + + * Windows port wants to use OpenSSL's implementation of SHA-1 + routines, so let them. + + * Add 32-bit Linux variant to the set of platforms to be tested with + Travis CI. + + * When a redirected http transport gets an error during the + redirected request, we ignored the error we got from the server, + and ended up giving a not-so-useful error message. + + * The patch subcommand of "git add -i" was meant to have paths + selection prompt just like other subcommand, unlike "git add -p" + directly jumps to hunk selection. Recently, this was broken and + "add -i" lost the paths selection dialog, but it now has been + fixed. + + * Git v2.12 was shipped with an embarrassing breakage where various + operations that verify paths given from the user stopped dying when + seeing an issue, and instead later triggering segfault. + + * The code to parse "git log -L..." command line was buggy when there + are many ranges specified with -L; overrun of the allocated buffer + has been fixed. + + * The command-line parsing of "git log -L" copied internal data + structures using incorrect size on ILP32 systems. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.13.0.txt b/Documentation/RelNotes/2.13.0.txt new file mode 100644 index 0000000000..0d4a3ef931 --- /dev/null +++ b/Documentation/RelNotes/2.13.0.txt @@ -0,0 +1,342 @@ +Git 2.13 Release Notes +====================== + +Backward compatibility notes. + + * Use of an empty string as a pathspec element that is used for + 'everything matches' is still warned and Git asks users to use a + more explicit '.' for that instead. The hope is that existing + users will not mind this change, and eventually the warning can be + turned into a hard error, upgrading the deprecation into removal of + this (mis)feature. That is not scheduled to happen in the upcoming + release (yet). + + * The historical argument order "git merge <msg> HEAD <commit>..." + has been deprecated for quite some time, and will be removed in a + future release. + + +Updates since v2.12 +------------------- + +UI, Workflows & Features + + * "git describe" and "git name-rev" have been taught to take more + than one refname patterns to restrict the set of refs to base their + naming output on, and also learned to take negative patterns to + name refs not to be used for naming via their "--exclude" option. + + * Deletion of a branch "foo/bar" could remove .git/refs/heads/foo + once there no longer is any other branch whose name begins with + "foo/", but we didn't do so so far. Now we do. + + * When "git merge" detects a path that is renamed in one history + while the other history deleted (or modified) it, it now reports + both paths to help the user understand what is going on in the two + histories being merged. + + * The <url> part in "http.<url>.<variable>" configuration variable + can now be spelled with '*' that serves as wildcard. + E.g. "http.https://*.example.com.proxy" can be used to specify the + proxy used for https://a.example.com, https://b.example.com, etc., + i.e. any host in the example.com domain. + + * "git tag" did not leave useful message when adding a new entry to + reflog; this was left unnoticed for a long time because refs/tags/* + doesn't keep reflog by default. + + * The "negative" pathspec feature was somewhat more cumbersome to use + than necessary in that its short-hand used "!" which needed to be + escaped from shells, and it required "exclude from what?" specified. + + * The command line options for ssh invocation needs to be tweaked for + some implementations of SSH (e.g. PuTTY plink wants "-P <port>" + while OpenSSH wants "-p <port>" to specify port to connect to), and + the variant was guessed when GIT_SSH environment variable is used + to specify it. The logic to guess now applies to the command + specified by the newer GIT_SSH_COMMAND and also core.sshcommand + configuration variable, and comes with an escape hatch for users to + deal with misdetected cases. + + * The "--git-path", "--git-common-dir", and "--shared-index-path" + options of "git rev-parse" did not produce usable output. They are + now updated to show the path to the correct file, relative to where + the caller is. + + * "git diff -W" has been taught to handle the case where a new + function is added at the end of the file better. + + * "git update-ref -d" and other operations to delete references did + not leave any entry in HEAD's reflog when the reference being + deleted was the current branch. This is not a problem in practice + because you do not want to delete the branch you are currently on, + but caused renaming of the current branch to something else not to + be logged in a useful way. + + * "Cc:" on the trailer part does not have to conform to RFC strictly, + unlike in the e-mail header. "git send-email" has been updated to + ignore anything after '>' when picking addresses, to allow non-address + cruft like " # stable 4.4" after the address. + (merge 9d3343961b jh/send-email-one-cc later to maint). + + * When "git submodule init" decides that the submodule in the working + tree is its upstream, it now gives a warning as it is not a very + common setup. + (merge d1b3b81aab sb/submodule-init-url-selection later to maint). + + * "git stash save" takes a pathspec so that the local changes can be + stashed away only partially. + (merge 9e140909f6 tg/stash-push later to maint). + + * Documentation for "git ls-files" did not refer to core.quotePath. + + * The experimental "split index" feature has gained a few + configuration variables to make it easier to use. + + * From a working tree of a repository, a new option of "rev-parse" + lets you ask if the repository is used as a submodule of another + project, and where the root level of the working tree of that + project (i.e. your superproject) is. + + * The pathspec mechanism learned to further limit the paths that + match the pattern to those that have specified attributes attached + via the gitattributes mechanism. + + * Our source code has used the SHA1_HEADER cpp macro after "#include" + in the C code to switch among the SHA-1 implementations. Instead, + list the exact header file names and switch among implementations + using "#ifdef BLK_SHA1/#include "block-sha1/sha1.h"/.../#endif"; + this helps some IDE tools. + + * The start-up sequence of "git" needs to figure out some configured + settings before it finds and set itself up in the location of the + repository and was quite messy due to its "chicken-and-egg" nature. + The code has been restructured. + + +Performance, Internal Implementation, Development Support etc. + + * The code to list branches in "git branch" has been consolidated + with the more generic ref-filter API. + + * Resource usage while enumerating refs from alternate object store + has been optimized to help receiving end of "push" that hosts a + repository with many "forks". + + * The gitattributes machinery is being taught to work better in a + multi-threaded environment. + + * "git rebase -i" starts using the recently updated "sequencer" code. + + * Code and design clean-up for the refs API. + + * The preload-index code has been taught not to bother with the index + entries that are paths that are not checked out by "sparse checkout". + + * Some warning() messages from "git clean" were updated to show the + errno from failed system calls. + + * The "parse_config_key()" API function has been cleaned up. + (merge ad8c7cdadd jk/parse-config-key-cleanup later to maint). + + * A test that creates a confusing branch whose name is HEAD has been + corrected not to do so. + (merge f0252ca23c jk/t6300-cleanup later to maint). + + * The code that parses header fields in the commit object has been + updated for (micro)performance and code hygiene. + (merge b072504ce1 rs/commit-parsing-optim later to maint). + + * An helper function to make it easier to append the result from + real_path() to a strbuf has been added. + (merge 33ad9ddd0b rs/strbuf-add-real-path later to maint). + + * Reduce authentication round-trip over HTTP when the server supports + just a single authentication method. This also improves the + behaviour when Git is misconfigured to enable http.emptyAuth + against a server that does not authenticate without a username + (i.e. not using Kerberos etc., which makes http.emptyAuth + pointless). + + * Windows port wants to use OpenSSL's implementation of SHA-1 + routines, so let them. + + * The t/perf performance test suite was not prepared to test not so + old versions of Git, but now it covers versions of Git that are not + so ancient. + (merge 28e1fb5466 jt/perf-updates later to maint). + + * Add 32-bit Linux variant to the set of platforms to be tested with + Travis CI. + + * "git branch --list" takes the "--abbrev" and "--no-abbrev" options + to control the output of the object name in its "-v"(erbose) + output, but a recent update started ignoring them; fix it before + the breakage reaches to any released version. + + * Picking two versions of Git and running tests to make sure the + older one and the newer one interoperate happily has now become + possible. + (merge bd4d9d993c jk/interop-test later to maint). + + * "uchar [40]" to "struct object_id" conversion continues. + + * "git tag --contains" used to (ab)use the object bits to keep track + of the state of object reachability without clearing them after + use; this has been cleaned up and made to use the newer commit-slab + facility. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.12 +----------------- + +Unless otherwise noted, all the fixes since v2.9 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * "git repack --depth=<n>" for a long time busted the specified depth + when reusing delta from existing packs. This has been corrected. + (merge 42b766d765 jk/delta-chain-limit later to maint). + + * The code to parse the command line "git grep <patterns>... <rev> + [[--] <pathspec>...]" has been cleaned up, and a handful of bugs + have been fixed (e.g. we used to check "--" if it is a rev). + (merge 131f3c96d2 jk/grep-no-index-fix later to maint). + + * "git ls-remote" and "git archive --remote" are designed to work + without being in a directory under Git's control. However, recent + updates revealed that we randomly look into a directory called + .git/ without actually doing necessary set-up when working in a + repository. Stop doing so. + (merge 4b0c3c7735 jn/remote-helpers-with-git-dir later to maint). + + * "git show-branch" expected there were only very short branch names + in the repository and used a fixed-length buffer to hold them + without checking for overflow. + (merge d3cc5f4c44 jk/show-branch-lift-name-len-limit later to maint). + + * A caller of tempfile API that uses stdio interface to write to + files may ignore errors while writing, which is detected when + tempfile is closed (with a call to ferror()). By that time, the + original errno that may have told us what went wrong is likely to + be long gone and was overwritten by an irrelevant value. + close_tempfile() now resets errno to EIO to make errno at least + predictable. + (merge 7e8c9355b7 jk/tempfile-ferror-fclose-confusion later to maint). + + * "git remote rm X", when a branch has remote X configured as the + value of its branch.*.remote, tried to remove branch.*.remote and + branch.*.merge and failed if either is unset. + (merge 20690b2139 rl/remote-allow-missing-branch-name-merge later to maint). + + * A "gc.log" file left by a backgrounded "gc --auto" disables further + automatic gc; it has been taught to run at least once a day (by + default) by ignoring a stale "gc.log" file that is too old. + (merge a831c06a2b dt/gc-ignore-old-gc-logs later to maint). + + * The code to parse "git -c VAR=VAL cmd" and set configuration + variable for the duration of cmd had two small bugs, which have + been fixed. + (merge 1274a155af jc/config-case-cmdline-take-2 later to maint). + + * user.email that consists of only cruft chars should consistently + error out, but didn't. + (merge 94425552f3 jk/ident-empty later to maint). + + * "git upload-pack", which is a counter-part of "git fetch", did not + report a request for a ref that was not advertised as invalid. + This is generally not a problem (because "git fetch" will stop + before making such a request), but is the right thing to do. + (merge bdb31eada7 jt/upload-pack-error-report later to maint). + + * A leak in a codepath to read from a packed object in (rare) cases + has been plugged. + (merge 886ddf4777 rs/sha1-file-plug-fallback-base-leak later to maint). + + * When a redirected http transport gets an error during the + redirected request, we ignored the error we got from the server, + and ended up giving a not-so-useful error message. + + * The patch subcommand of "git add -i" was meant to have paths + selection prompt just like other subcommand, unlike "git add -p" + directly jumps to hunk selection. Recently, this was broken and + "add -i" lost the paths selection dialog, but it now has been + fixed. + + * Git v2.12 was shipped with an embarrassing breakage where various + operations that verify paths given from the user stopped dying when + seeing an issue, and instead later triggering segfault. + + * There is no need for Python only to give a few messages to the + standard error stream, but we somehow did. + (merge b8686c661d ss/remote-bzr-hg-placeholder-wo-python later to maint). + + * The code to parse "git log -L..." command line was buggy when there + are many ranges specified with -L; overrun of the allocated buffer + has been fixed. + + * The command-line parsing of "git log -L" copied internal data + structures using incorrect size on ILP32 systems. + + * "git diff --quiet" relies on the size field in diff_filespec to be + correctly populated, but diff_populate_filespec() helper function + made an incorrect short-cut when asked only to populate the size + field for paths that need to go through convert_to_git() (e.g. CRLF + conversion). + (merge 12426e114b jc/diff-populate-filespec-size-only-fix later to maint). + + * A few tests were run conditionally under (rare) conditions where + they cannot be run (like running cvs tests under 'root' account). + (merge c6507484a2 ab/cond-skip-tests later to maint). + + * "git branch @" created refs/heads/@ as a branch, and in general the + code that handled @{-1} and @{upstream} was a bit too loose in + disambiguating. + (merge fd4692ff70 jk/interpret-branch-name later to maint). + + * "git fetch" that requests a commit by object name, when the other + side does not allow such an request, failed without much + explanation. + (merge d56583ded6 mm/fetch-show-error-message-on-unadvertised-object later to maint). + + * "git filter-branch --prune-empty" drops a single-parent commit that + becomes a no-op, but did not drop a root commit whose tree is empty. + (merge 32da7467eb dp/filter-branch-prune-empty later to maint). + + * Recent versions of Git treats http alternates (used in dumb http + transport) just like HTTP redirects and requires the client to + enable following it, due to security concerns. But we forgot to + give a warning when we decide not to honor the alternates. + (merge 5cae73d5d2 ew/http-alternates-as-redirects-warning later to maint). + + * "git push" had a handful of codepaths that could lead to a deadlock + when unexpected error happened, which has been fixed. + (merge d1a13d3fcb jk/push-deadlock-regression-fix later to maint). + + * "Dumb http" transport used to misparse a nonsense http-alternates + response, which has been fixed. + (merge d61434ae81 jk/http-walker-buffer-underflow-fix later to maint). + + * "git add -p <pathspec>" unnecessarily expanded the pathspec to a + list of individual files that matches the pathspec by running "git + ls-files <pathspec>", before feeding it to "git diff-index" to see + which paths have changes, because historically the pathspec + language supported by "diff-index" was weaker. These days they are + equivalent and there is no reason to internally expand it. This + helps both performance and avoids command line argument limit on + some platforms. + (merge 7288e12cce jk/add-i-use-pathspecs later to maint). + + * "git status --porcelain" is supposed to give a stable output, but a + few strings were left as translatable by mistake. + (merge b9e2bc560a mg/status-porcelain-no-i18n later to maint). + + * Other minor doc, test and build updates and code cleanups. + (merge b803ae4427 ps/docs-diffcore later to maint). + (merge bcd886d897 ew/markdown-url-in-readme later to maint). + (merge b2d593a779 rj/remove-unused-mktemp later to maint). + (merge 3255e512a8 jk/ewah-use-right-type-in-sizeof later to maint). + (merge dfa3ad3238 rs/blame-code-cleanup later to maint). diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 2669b87c9d..dc41957afa 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -77,7 +77,7 @@ include::line-range-format.txt[] terminal. Can't use `--progress` together with `--porcelain` or `--incremental`. --M|<num>|:: +-M[<num>]:: Detect moved or copied lines within a file. When a commit moves or copies a block of lines (e.g. the original file has A and then B, and the commit changes it to B and then @@ -93,7 +93,7 @@ alphanumeric characters that Git must detect as moving/copying within a file for it to associate those lines with the parent commit. The default value is 20. --C|<num>|:: +-C[<num>]:: In addition to `-M`, detect lines moved or copied from other files that were modified in the same commit. This is useful when you reorganize your program and move code diff --git a/Documentation/config.txt b/Documentation/config.txt index fc5a28a320..cf281f64f1 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -79,18 +79,69 @@ escape sequences) are invalid. Includes ~~~~~~~~ -You can include one config file from another by setting the special +You can include a config file from another by setting the special `include.path` variable to the name of the file to be included. The variable takes a pathname as its value, and is subject to tilde -expansion. +expansion. `include.path` can be given multiple times. -The -included file is expanded immediately, as if its contents had been +The included file is expanded immediately, as if its contents had been found at the location of the include directive. If the value of the -`include.path` variable is a relative path, the path is considered to be -relative to the configuration file in which the include directive was -found. See below for examples. +`include.path` variable is a relative path, the path is considered to +be relative to the configuration file in which the include directive +was found. See below for examples. +Conditional includes +~~~~~~~~~~~~~~~~~~~~ + +You can include a config file from another conditionally by setting a +`includeIf.<condition>.path` variable to the name of the file to be +included. The variable's value is treated the same way as +`include.path`. `includeIf.<condition>.path` can be given multiple times. + +The condition starts with a keyword followed by a colon and some data +whose format and meaning depends on the keyword. Supported keywords +are: + +`gitdir`:: + + The data that follows the keyword `gitdir:` is used as a glob + pattern. If the location of the .git directory matches the + pattern, the include condition is met. ++ +The .git location may be auto-discovered, or come from `$GIT_DIR` +environment variable. If the repository is auto discovered via a .git +file (e.g. from submodules, or a linked worktree), the .git location +would be the final location where the .git directory is, not where the +.git file is. ++ +The pattern can contain standard globbing wildcards and two additional +ones, `**/` and `/**`, that can match multiple path components. Please +refer to linkgit:gitignore[5] for details. For convenience: + + * If the pattern starts with `~/`, `~` will be substituted with the + content of the environment variable `HOME`. + + * If the pattern starts with `./`, it is replaced with the directory + containing the current config file. + + * If the pattern does not start with either `~/`, `./` or `/`, `**/` + will be automatically prepended. For example, the pattern `foo/bar` + becomes `**/foo/bar` and would match `/any/path/to/foo/bar`. + + * If the pattern ends with `/`, `**` will be automatically added. For + example, the pattern `foo/` becomes `foo/**`. In other words, it + matches "foo" and everything inside, recursively. + +`gitdir/i`:: + This is the same as `gitdir` except that matching is done + case-insensitively (e.g. on case-insensitive file sytems) + +A few more notes on matching via `gitdir` and `gitdir/i`: + + * Symlinks in `$GIT_DIR` are not resolved before matching. + + * Note that "../" is not special and will match literally, which is + unlikely what you want. Example ~~~~~~~ @@ -119,6 +170,17 @@ Example path = foo ; expand "foo" relative to the current file path = ~/foo ; expand "foo" in your `$HOME` directory + ; include if $GIT_DIR is /path/to/foo/.git + [includeIf "gitdir:/path/to/foo/.git"] + path = /path/to/foo.inc + + ; include for all repositories inside /path/to/group + [includeIf "gitdir:/path/to/group/"] + path = /path/to/foo.inc + + ; include for all repositories inside $HOME/to/group + [includeIf "gitdir:~/to/group/"] + path = /path/to/foo.inc Values ~~~~~~ @@ -334,6 +396,10 @@ core.trustctime:: crawlers and some backup systems). See linkgit:git-update-index[1]. True by default. +core.splitIndex:: + If true, the split-index feature of the index will be used. + See linkgit:git-update-index[1]. False by default. + core.untrackedCache:: Determines what to do about the untracked cache feature of the index. It will be kept, if this variable is unset or set to @@ -350,16 +416,19 @@ core.checkStat:: all fields, including the sub-second part of mtime and ctime. core.quotePath:: - The commands that output paths (e.g. 'ls-files', - 'diff'), when not given the `-z` option, will quote - "unusual" characters in the pathname by enclosing the - pathname in a double-quote pair and with backslashes the - same way strings in C source code are quoted. If this - variable is set to false, the bytes higher than 0x80 are - not quoted but output as verbatim. Note that double - quote, backslash and control characters are always - quoted without `-z` regardless of the setting of this - variable. + Commands that output paths (e.g. 'ls-files', 'diff'), will + quote "unusual" characters in the pathname by enclosing the + pathname in double-quotes and escaping those characters with + backslashes in the same way C escapes control characters (e.g. + `\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with + values larger than 0x80 (e.g. octal `\302\265` for "micro" in + UTF-8). If this variable is set to false, bytes higher than + 0x80 are not considered "unusual" any more. Double-quotes, + backslash and control characters are always escaped regardless + of the setting of this variable. A simple space character is + not considered "unusual". Many commands can output pathnames + completely verbatim using the `-z` option. The default value + is true. core.eol:: Sets the line ending type to use in the working directory for @@ -1402,6 +1471,12 @@ gc.autoDetach:: Make `git gc --auto` return immediately and run in background if the system supports it. Default is true. +gc.logExpiry:: + If the file gc.log exists, then `git gc --auto` won't run + unless that file is more than 'gc.logExpiry' old. Default is + "1.day". See `gc.pruneExpire` for more ways to specify its + value. + gc.packRefs:: Running `git pack-refs` in a repository renders it unclonable by Git versions prior to 1.5.1.2 over dumb @@ -1919,7 +1994,10 @@ http.<url>.*:: must match exactly between the config key and the URL. . Host/domain name (e.g., `example.com` in `https://example.com/`). - This field must match exactly between the config key and the URL. + This field must match between the config key and the URL. It is + possible to specify a `*` as part of the host name to match all subdomains + at this level. `https://*.example.com/` for example would match + `https://foo.example.com/`, but not `https://foo.bar.example.com/`. . Port number (e.g., `8080` in `http://example.com:8080/`). This field must match exactly between the config key and the URL. @@ -1954,6 +2032,17 @@ Environment variable settings always override any matches. The URLs that are matched against are those given directly to Git commands. This means any URLs visited as a result of a redirection do not participate in matching. +ssh.variant:: + Depending on the value of the environment variables `GIT_SSH` or + `GIT_SSH_COMMAND`, or the config setting `core.sshCommand`, Git + auto-detects whether to adjust its command-line parameters for use + with plink or tortoiseplink, as opposed to the default (OpenSSH). ++ +The config variable `ssh.variant` can be set to override this auto-detection; +valid values are `ssh`, `plink`, `putty` or `tortoiseplink`. Any other value +will be treated as normal ssh. This setting can be overridden via the +environment variable `GIT_SSH_VARIANT`. + i18n.commitEncoding:: Character encoding the commit messages are stored in; Git itself does not care per se, but this information is necessary e.g. when @@ -2827,6 +2916,31 @@ showbranch.default:: The default set of branches for linkgit:git-show-branch[1]. See linkgit:git-show-branch[1]. +splitIndex.maxPercentChange:: + When the split index feature is used, this specifies the + percent of entries the split index can contain compared to the + total number of entries in both the split index and the shared + index before a new shared index is written. + The value should be between 0 and 100. If the value is 0 then + a new shared index is always written, if it is 100 a new + shared index is never written. + By default the value is 20, so a new shared index is written + if the number of entries in the split index would be greater + than 20 percent of the total number of entries. + See linkgit:git-update-index[1]. + +splitIndex.sharedIndexExpire:: + When the split index feature is used, shared index files that + were not modified since the time this variable specifies will + be removed when a new shared index file is created. The value + "now" expires all entries immediately, and "never" suppresses + expiration altogether. + The default value is "2.weeks.ago". + Note that a shared index file is considered modified (for the + purpose of expiration) each time a new split-index file is + either created based on it or read from it. + See linkgit:git-update-index[1]. + status.relativePaths:: By default, linkgit:git-status[1] shows paths relative to the current directory. Setting this variable to `false` shows paths @@ -2949,7 +3063,7 @@ submodule.alternateLocation:: value is set to `superproject` the submodule to be cloned computes its alternates location relative to the superprojects alternate. -submodule.alternateErrorStrategy +submodule.alternateErrorStrategy:: Specifies how to treat errors with the alternates for a submodule as computed via `submodule.alternateLocation`. Possible values are `ignore`, `info`, `die`. Default is `die`. diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index cf5262622f..706916c94c 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -78,9 +78,10 @@ Example: :100644 100644 5be4a4...... 000000...... M file.c ------------------------------------------------ -When `-z` option is not used, TAB, LF, and backslash characters -in pathnames are represented as `\t`, `\n`, and `\\`, -respectively. +Without the `-z` option, pathnames with "unusual" characters are +quoted as explained for the configuration variable `core.quotePath` +(see linkgit:git-config[1]). Using `-z` the filename is output +verbatim and the line is terminated by a NUL byte. diff format for merges ---------------------- diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index d2a7ff56e8..231105cff4 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -53,10 +53,9 @@ The index line includes the SHA-1 checksum before and after the change. The <mode> is included if the file mode does not change; otherwise, separate lines indicate the old and the new mode. -3. TAB, LF, double quote and backslash characters in pathnames - are represented as `\t`, `\n`, `\"` and `\\`, respectively. - If there is need for such substitution then the whole - pathname is put in double quotes. +3. Pathnames with "unusual" characters are quoted as explained for + the configuration variable `core.quotePath` (see + linkgit:git-config[1]). 4. All the `file1` files in the output refer to files before the commit, and all the `file2` files refer to files after the commit. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index d91ddbd5fe..89cc0f48de 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -192,10 +192,9 @@ ifndef::git-log[] given, do not munge pathnames and use NULs as output field terminators. endif::git-log[] + -Without this option, each pathname output will have TAB, LF, double quotes, -and backslash characters replaced with `\t`, `\n`, `\"`, and `\\`, -respectively, and the pathname will be enclosed in double quotes if -any of those replacements occurred. +Without this option, pathnames with "unusual" characters are quoted as +explained for the configuration variable `core.quotePath` (see +linkgit:git-config[1]). --name-only:: Show only names of changed files. diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 8ddb207409..631cbd840a 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -108,10 +108,9 @@ the information is read from the current index instead. When `--numstat` has been given, do not munge pathnames, but use a NUL-terminated machine-readable format. + -Without this option, each pathname output will have TAB, LF, double quotes, -and backslash characters replaced with `\t`, `\n`, `\"`, and `\\`, -respectively, and the pathname will be enclosed in double quotes if -any of those replacements occurred. +Without this option, pathnames with "unusual" characters are quoted as +explained for the configuration variable `core.quotePath` (see +linkgit:git-config[1]). -p<n>:: Remove <n> leading slashes from traditional diff paths. The diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 28d46cc03b..092f1bcf9f 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -12,7 +12,7 @@ SYNOPSIS [--list] [-v [--abbrev=<length> | --no-abbrev]] [--column[=<options>] | --no-column] [(--merged | --no-merged | --contains) [<commit>]] [--sort=<key>] - [--points-at <object>] [<pattern>...] + [--points-at <object>] [--format=<format>] [<pattern>...] 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] 'git branch' --unset-upstream [<branchname>] @@ -253,6 +253,11 @@ start-point is either a local or remote-tracking branch. --points-at <object>:: Only list branches of the given object. +--format <format>:: + A string that interpolates `%(fieldname)` from the object + pointed at by a ref being shown. The format is the same as + that of linkgit:git-for-each-ref[1]. + Examples -------- diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 8611a99120..92777cef25 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -100,10 +100,10 @@ OPTIONS --normalize:: Normalize 'refname' by removing any leading slash (`/`) characters and collapsing runs of adjacent slashes between - name components into a single slash. Iff the normalized + name components into a single slash. If the normalized refname is valid then print it to standard output and exit - with a status of 0. (`--print` is a deprecated way to spell - `--normalize`.) + with a status of 0, otherwise exit with a non-zero status. + (`--print` is a deprecated way to spell `--normalize`.) EXAMPLES diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 4f8f20a360..25dcdcc289 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -117,9 +117,12 @@ OPTIONS -z:: --null:: - When showing `short` or `porcelain` status output, terminate - entries in the status output with NUL, instead of LF. If no - format is given, implies the `--porcelain` output format. + When showing `short` or `porcelain` status output, print the + filename verbatim and terminate the entries with NUL, instead of LF. + If no format is given, implies the `--porcelain` output format. + Without the `-z` option, filenames with "unusual" characters are + quoted as explained for the configuration variable `core.quotePath` + (see linkgit:git-config[1]). -F <file>:: --file=<file>:: diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index e4ac448ff5..8755f3af7b 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -83,7 +83,20 @@ OPTIONS --match <pattern>:: Only consider tags matching the given `glob(7)` pattern, excluding the "refs/tags/" prefix. This can be used to avoid - leaking private tags from the repository. + leaking private tags from the repository. If given multiple times, a + list of patterns will be accumulated, and tags matching any of the + patterns will be considered. Use `--no-match` to clear and reset the + list of patterns. + +--exclude <pattern>:: + Do not consider tags matching the given `glob(7)` pattern, excluding + the "refs/tags/" prefix. This can be used to narrow the tag space and + find only tags matching some meaningful criteria. If given multiple + times, a list of patterns will be accumulated and tags matching any + of the patterns will be excluded. When combined with --match a tag will + be considered when it matches at least one --match pattern and does not + match any of the --exclude patterns. Use `--no-exclude` to clear and + reset the list of patterns. --always:: Show uniquely abbreviated commit object as fallback. diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 224fb3090b..96c26e6aa8 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -86,10 +86,11 @@ instead. `--no-symlinks` is the default on Windows. Additionally, `$BASE` is set in the environment. -g:: ---gui:: +--[no-]gui:: When 'git-difftool' is invoked with the `-g` or `--gui` option the default diff tool will be read from the configured - `diff.guitool` variable instead of `diff.tool`. + `diff.guitool` variable instead of `diff.tool`. The `--no-gui` + option can be used to override this setting. --[no-]trust-exit-code:: 'git-difftool' invokes a diff tool individually on each file. diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 0a09698c03..6e4bb02204 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -167,14 +167,12 @@ to other tags will be rewritten to point to the underlying commit. project root. Implies <<Remap_to_ancestor>>. --prune-empty:: - Some kind of filters will generate empty commits, that left the tree - 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 - 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. + Some filters will generate empty commits that leave the tree untouched. + This option instructs git-filter-branch to remove such commits if they + have exactly one or zero non-pruned parents; merge commits will + therefore remain intact. This option cannot be used together with + `--commit-filter`, though the same effect can be achieved by using the + provided `git_commit_non_empty_tree` function in a commit filter. --original <namespace>:: Use this option to set the namespace where the original commits diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index abe13f3bed..111e1be6f5 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -95,11 +95,20 @@ refname:: The name of the ref (the part after $GIT_DIR/). For a non-ambiguous short name of the ref append `:short`. The option core.warnAmbiguousRefs is used to select the strict - abbreviation mode. If `strip=<N>` is appended, strips `<N>` - slash-separated path components from the front of the refname - (e.g., `%(refname:strip=2)` turns `refs/tags/foo` into `foo`. - `<N>` must be a positive integer. If a displayed ref has fewer - components than `<N>`, the command aborts with an error. + abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>` + slash-separated path components from the front (back) of the refname + (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and + `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`). + If `<N>` is a negative number, strip as many path components as + necessary from the specified end to leave `-<N>` path components + (e.g. `%(refname:lstrip=-2)` turns + `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)` + turns `refs/tags/foo` into `refs`). When the ref does not have + enough components, the result becomes an empty string if + stripping with positive <N>, or it becomes the full refname if + stripping with negative <N>. Neither is an error. ++ +`strip` can be used as a synomym to `lstrip`. objecttype:: The type of the object (`blob`, `tree`, `commit`, `tag`). @@ -110,21 +119,31 @@ objectsize:: objectname:: The object name (aka SHA-1). For a non-ambiguous abbreviation of the object name append `:short`. + For an abbreviation of the object name with desired length append + `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The + length may be exceeded to ensure unique object names. upstream:: The name of a local ref which can be considered ``upstream'' - from the displayed ref. Respects `:short` in the same way as - `refname` above. Additionally respects `:track` to show - "[ahead N, behind M]" and `:trackshort` to show the terse - version: ">" (ahead), "<" (behind), "<>" (ahead and behind), - or "=" (in sync). Has no effect if the ref does not have - tracking information associated with it. + from the displayed ref. Respects `:short`, `:lstrip` and + `:rstrip` in the same way as `refname` above. Additionally + respects `:track` to show "[ahead N, behind M]" and + `:trackshort` to show the terse version: ">" (ahead), "<" + (behind), "<>" (ahead and behind), or "=" (in sync). `:track` + also prints "[gone]" whenever unknown upstream ref is + encountered. Append `:track,nobracket` to show tracking + information without brackets (i.e "ahead N, behind M"). Has + no effect if the ref does not have tracking information + associated with it. All the options apart from `nobracket` + are mutually exclusive, but if used together the last option + is selected. push:: - The name of a local ref which represents the `@{push}` location - for the displayed ref. Respects `:short`, `:track`, and - `:trackshort` options as `upstream` does. Produces an empty - string if no `@{push}` ref is configured. + The name of a local ref which represents the `@{push}` + location for the displayed ref. Respects `:short`, `:lstrip`, + `:rstrip`, `:track`, and `:trackshort` options as `upstream` + does. Produces an empty string if no `@{push}` ref is + configured. HEAD:: '*' if HEAD matches current ref (the checked out branch), ' ' @@ -149,6 +168,25 @@ align:: quoted, but if nested then only the topmost level performs quoting. +if:: + Used as %(if)...%(then)...%(end) or + %(if)...%(then)...%(else)...%(end). If there is an atom with + value or string literal after the %(if) then everything after + the %(then) is printed, else if the %(else) atom is used, then + everything after %(else) is printed. We ignore space when + evaluating the string before %(then), this is useful when we + use the %(HEAD) atom which prints either "*" or " " and we + want to apply the 'if' condition only on the 'HEAD' ref. + Append ":equals=<string>" or ":notequals=<string>" to compare + the value between the %(if:...) and %(then) atoms with the + given string. + +symref:: + The ref which the given symbolic ref refers to. If not a + symbolic ref, nothing is printed. Respects the `:short`, + `:lstrip` and `:rstrip` options in the same way as `refname` + above. + In addition to the above, for commit and tag objects, the header field names (`tree`, `parent`, `object`, `type`, and `tag`) can be used to specify the value in the header field. @@ -186,6 +224,14 @@ As a special case for the date-type fields, you may specify a format for the date by adding `:` followed by date format name (see the values the `--date` option to linkgit:git-rev-list[1] takes). +Some atoms like %(align) and %(if) always require a matching %(end). +We call them "opening atoms" and sometimes denote them as %($open). + +When a scripting language specific quoting is in effect, everything +between a top-level opening atom and its matching %(end) is evaluated +according to the semantics of the opening atom and only its result +from the top-level is quoted. + EXAMPLES -------- @@ -273,6 +319,22 @@ eval=`git for-each-ref --shell --format="$fmt" \ eval "$eval" ------------ + +An example to show the usage of %(if)...%(then)...%(else)...%(end). +This prefixes the current branch with a star. + +------------ +git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/ +------------ + + +An example to show the usage of %(if)...%(then)...%(end). +This prints the authorname, if present. + +------------ +git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)" +------------ + SEE ALSO -------- linkgit:git-show-ref[1] diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 852b72c679..571b5a7e3c 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -127,7 +127,7 @@ 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` -controls --depth option in linkgit:git-repack[1]. This defaults to 250. +controls --depth option in linkgit:git-repack[1]. This defaults to 50. The optional configuration variable `gc.pruneExpire` controls how old the unreferenced loose objects have to be before they are pruned. The diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 9d27197de8..3c5a67fb96 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -116,8 +116,8 @@ does not exist, it will be created. TEMPLATE DIRECTORY ------------------ -The template directory contains files and directories that will be copied to -the `$GIT_DIR` after it is created. +Files and directories in the template directory whose name do not start with a +dot will be copied to the `$GIT_DIR` after it is created. The template directory will be one of the following (in order): diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 446209e206..1cab703f73 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -77,7 +77,8 @@ OPTIONS succeed. -z:: - \0 line termination on output. + \0 line termination on output and do not quote filenames. + See OUTPUT below for more information. -x <pattern>:: --exclude=<pattern>:: @@ -196,9 +197,10 @@ the index records up to three such pairs; one from tree O in stage the user (or the porcelain) to see what should eventually be recorded at the path. (see linkgit:git-read-tree[1] for more information on state) -When `-z` option is not used, TAB, LF, and backslash characters -in pathnames are represented as `\t`, `\n`, and `\\`, -respectively. +Without the `-z` option, pathnames with "unusual" characters are +quoted as explained for the configuration variable `core.quotePath` +(see linkgit:git-config[1]). Using `-z` the filename is output +verbatim and the line is terminated by a NUL byte. Exclude Patterns diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index dbc91f98ff..9dee7bef35 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -53,7 +53,8 @@ OPTIONS Show object size of blob (file) entries. -z:: - \0 line termination on output. + \0 line termination on output and do not quote filenames. + See OUTPUT FORMAT below for more information. --name-only:: --name-status:: @@ -82,8 +83,6 @@ Output Format ------------- <mode> SP <type> SP <object> TAB <file> -Unless the `-z` option is used, TAB, LF, and backslash characters -in pathnames are represented as `\t`, `\n`, and `\\`, respectively. This output format is compatible with what `--index-info --stdin` of 'git update-index' expects. @@ -95,6 +94,11 @@ Object size identified by <object> is given in bytes, and right-justified with minimum width of 7 characters. Object size is given only for blobs (file) entries; for other entries `-` character is used in place of size. +Without the `-z` option, pathnames with "unusual" characters are +quoted as explained for the configuration variable `core.quotePath` +(see linkgit:git-config[1]). Using `-z` the filename is output +verbatim and the line is terminated by a NUL byte. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index ca28fb8e2a..e8e68f528c 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -26,7 +26,18 @@ OPTIONS --refs=<pattern>:: Only use refs whose names match a given shell pattern. The pattern - can be one of branch name, tag name or fully qualified ref name. + can be one of branch name, tag name or fully qualified ref name. If + given multiple times, use refs whose names match any of the given shell + patterns. Use `--no-refs` to clear any previous ref patterns given. + +--exclude=<pattern>:: + Do not use any ref whose name matches a given shell pattern. The + pattern can be one of branch name, tag name or fully qualified ref + name. If given multiple times, a ref will be excluded when it matches + any of the given patterns. When used together with --refs, a ref will + be used as a match only when it matches at least one --refs pattern and + does not match any --exclude patterns. Use `--no-exclude` to clear the + list of exclude patterns. --all:: List all commits reachable from all refs diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 8eefabd0d1..1624a35888 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -272,7 +272,7 @@ origin +master` to force a push to the `master` branch). See the standard error stream is not directed to a terminal. --no-recurse-submodules:: ---recurse-submodules=check|on-demand|no:: +--recurse-submodules=check|on-demand|only|no:: May be used to make sure all submodule commits used by the revisions to be pushed are available on a remote-tracking branch. If 'check' is used Git will verify that all submodule commits that @@ -280,11 +280,12 @@ origin +master` to force a push to the `master` branch). See the remote of the submodule. If any commits are missing the push will be aborted and exit with non-zero status. If 'on-demand' is used 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 - push.recurseSubmodules configuration variable when no submodule - recursion is required. + pushed. If on-demand was not able to push all necessary revisions it will + also be aborted and exit with non-zero status. If 'only' is used all + submodules will be recursively pushed while the superproject is left + unpushed. A value of 'no' or using `--no-recurse-submodules` can be used + to override the push.recurseSubmodules configuration variable when no + submodule recursion is required. --[no-]verify:: Toggle the pre-push hook (see linkgit:githooks[5]). The diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 25432d9257..8a21198d65 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -292,6 +292,54 @@ $ git reset --keep start <3> <3> But you can use "reset --keep" to remove the unwanted commit after you switched to "branch2". +Split a commit apart into a sequence of commits:: ++ +Suppose that you have created lots of logically separate changes and commited +them together. Then, later you decide that it might be better to have each +logical chunk associated with its own commit. You can use git reset to rewind +history without changing the contents of your local files, and then successively +use `git add -p` to interactively select which hunks to include into each commit, +using `git commit -c` to pre-populate the commit message. ++ +------------ +$ git reset -N HEAD^ <1> +$ git add -p <2> +$ git diff --cached <3> +$ git commit -c HEAD@{1} <4> +... <5> +$ git add ... <6> +$ git diff --cached <7> +$ git commit ... <8> +------------ ++ +<1> First, reset the history back one commit so that we remove the original + commit, but leave the working tree with all the changes. The -N ensures + that any new files added with HEAD are still marked so that git add -p + will find them. +<2> Next, we interactively select diff hunks to add using the git add -p + facility. This will ask you about each diff hunk in sequence and you can + use simple commands such as "yes, include this", "No don't include this" + or even the very powerful "edit" facility. +<3> Once satisfied with the hunks you want to include, you should verify what + has been prepared for the first commit by using git diff --cached. This + shows all the changes that have been moved into the index and are about + to be committed. +<4> Next, commit the changes stored in the index. The -c option specifies to + pre-populate the commit message from the original message that you started + with in the first commit. This is helpful to avoid retyping it. The HEAD@{1} + is a special notation for the commit that HEAD used to be at prior to the + original reset commit (1 change ago). See linkgit:git-reflog[1] for more + details. You may also use any other valid commit reference. +<5> You can repeat steps 2-4 multiple times to break the original code into + any number of commits. +<6> Now you've split out many of the changes into their own commits, and might + no longer use the patch mode of git add, in order to select all remaining + uncommitted changes. +<7> Once again, check to verify that you've included what you want to. You may + also wish to verify that git diff doesn't show any remaining changes to be + committed later. +<8> And finally create the final commit. + DISCUSSION ---------- diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 7241e96893..c40c470448 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -217,6 +217,10 @@ If `$GIT_DIR` is not defined and the current directory is not detected to lie in a Git repository or work tree print a message to stderr and exit with nonzero status. +--absolute-git-dir:: + Like `--git-dir`, but its output is always the canonicalized + absolute path. + --git-common-dir:: Show `$GIT_COMMON_DIR` if defined, else `$GIT_DIR`. @@ -257,6 +261,12 @@ print a message to stderr and exit with nonzero status. --show-toplevel:: Show the absolute path of the top-level directory. +--show-superproject-working-tree + Show the absolute path of the root of the superproject's + working tree (if exists) that uses the current repository as + its submodule. Outputs nothing if the current repository is + not used as a submodule by any project. + --shared-index-path:: Show the path to the shared index file in split index mode, or empty if not in split-index mode. diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 2e9cef06e6..70191d06b6 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -13,8 +13,11 @@ SYNOPSIS 'git stash' drop [-q|--quiet] [<stash>] 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] - [-u|--include-untracked] [-a|--all] [<message>]] +'git stash' save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] + [-u|--include-untracked] [-a|--all] [<message>] +'git stash' [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] + [-u|--include-untracked] [-a|--all] [-m|--message <message>]] + [--] [<pathspec>...]] 'git stash' clear 'git stash' create [<message>] 'git stash' store [-m|--message <message>] [-q|--quiet] <commit> @@ -46,13 +49,24 @@ OPTIONS ------- save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]:: +push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--] [<pathspec>...]:: - Save your local modifications to a new 'stash', and run `git reset - --hard` to revert them. The <message> part is optional and gives - the description along with the stashed state. For quickly making - a snapshot, you can omit _both_ "save" and <message>, but giving - only <message> does not trigger this action to prevent a misspelled - subcommand from making an unwanted stash. + Save your local modifications to a new 'stash' and roll them + back to HEAD (in the working tree and in the index). + The <message> part is optional and gives + the description along with the stashed state. ++ +For quickly making a snapshot, you can omit "push". In this mode, +non-option arguments are not allowed to prevent a misspelled +subcommand from making an unwanted stash. The two exceptions to this +are `stash -p` which acts as alias for `stash push -p` and pathspecs, +which are allowed after a double hyphen `--` for disambiguation. ++ +When pathspec is given to 'git stash push', the new stash records the +modified states only for the files that match the pathspec. The index +entries and working tree files are then rolled back to the state in +HEAD only for these files, too, leaving files that do not match the +pathspec intact. + If the `--keep-index` option is used, all changes already added to the index are left intact. diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 725065ef2d..ba873657cf 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -322,10 +322,9 @@ When the `-z` option is given, pathnames are printed as is and without any quoting and lines are terminated with a NUL (ASCII 0x00) byte. -Otherwise, all pathnames will be "C-quoted" if they contain any tab, -linefeed, double quote, or backslash characters. In C-quoting, these -characters will be replaced with the corresponding C-style escape -sequences and the resulting pathname will be double quoted. +Without the `-z` option, pathnames with "unusual" characters are +quoted as explained for the configuration variable `core.quotePath` +(see linkgit:git-config[1]). CONFIGURATION diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 918bd1d1bd..e05d0cddef 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,17 +9,12 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>] - [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] +'git submodule' [--quiet] add [<options>] [--] <repository> [<path>] 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...) -'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] - [--[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] update [<options>] [--] [<path>...] +'git submodule' [--quiet] summary [<options>] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> 'git submodule' [--quiet] sync [--recursive] [--] [<path>...] 'git submodule' [--quiet] absorbgitdirs [--] [<path>...] @@ -63,7 +58,7 @@ if you choose to go that route. COMMANDS -------- -add:: +add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]:: Add the given repository as a submodule at the given path to the changeset to be committed next to the current project: the current project is termed the "superproject". @@ -78,13 +73,17 @@ configuration entries unless `--name` is used to specify a logical name. + <repository> is the URL of the new submodule's origin repository. This may be either an absolute URL, or (if it begins with ./ -or ../), the location relative to the superproject's origin +or ../), the location relative to the superproject's default remote repository (Please note that to specify a repository 'foo.git' which is located right next to a superproject 'bar.git', you'll have to use '../foo.git' instead of './foo.git' - as one might expect when following the rules for relative URLs - because the evaluation of relative URLs in Git is identical to that of relative directories). -If the superproject doesn't have an origin configured ++ +The default remote is the remote of the remote tracking branch +of the current branch. If no such remote tracking branch exists or +the HEAD is detached, "origin" is assumed to be the default remote. +If the superproject doesn't have a default remote configured the superproject is its own authoritative upstream and the current working directory is used instead. + @@ -104,7 +103,7 @@ together in the same relative location, and only the superproject's URL needs to be provided: git-submodule will correctly locate the submodule using the relative URL in .gitmodules. -status:: +status [--cached] [--recursive] [--] [<path>...]:: Show the status of the submodules. This will print the SHA-1 of the currently checked out commit for each submodule, along with the submodule path and the output of 'git describe' for the @@ -121,22 +120,28 @@ submodules with respect to the commit recorded in the index or the HEAD, linkgit:git-status[1] and linkgit:git-diff[1] will provide that information too (and can also report changes to a submodule's work tree). -init:: +init [--] [<path>...]:: Initialize the submodules recorded in the index (which were - added and committed elsewhere) by copying submodule - names and urls from .gitmodules to .git/config. - Optional <path> arguments limit which submodules will be initialized. - It will also copy the value of `submodule.$name.update` into - .git/config. - The key used in .git/config is `submodule.$name.url`. - This command does not alter existing information in .git/config. - You can then customize the submodule clone URLs in .git/config - for your local setup and proceed to `git submodule update`; - you can also just use `git submodule update --init` without - the explicit 'init' step if you do not intend to customize - any submodule locations. - -deinit:: + added and committed elsewhere) by setting `submodule.$name.url` + in .git/config. It uses the same setting from .gitmodules as + a template. If the URL is relative, it will be resolved using + the default remote. If there is no default remote, the current + repository will be assumed to be upstream. ++ +Optional <path> arguments limit which submodules will be initialized. +If no path is specified, all submodules are initialized. ++ +When present, it will also copy the value of `submodule.$name.update`. +This command does not alter existing information in .git/config. +You can then customize the submodule clone URLs in .git/config +for your local setup and proceed to `git submodule update`; +you can also just use `git submodule update --init` without +the explicit 'init' step if you do not intend to customize +any submodule locations. ++ +See the add subcommand for the defintion of default remote. + +deinit [-f|--force] (--all|[--] <path>...):: Unregister the given submodules, i.e. remove the whole `submodule.$name` section from .git/config together with their work tree. Further calls to `git submodule update`, `git submodule foreach` @@ -152,20 +157,20 @@ instead of deinit-ing everything, to prevent mistakes. If `--force` is specified, the submodule's working tree will be removed even if it contains local modifications. -update:: +update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]:: + -- Update the registered submodules to match what the superproject expects by cloning missing submodules and updating the working tree of the submodules. The "updating" can be done in several ways depending on command line options and the value of `submodule.<name>.update` -configuration variable. Supported update procedures are: +configuration variable. The command line option takes precedence over +the configuration variable. if neither is given, a checkout is performed. +update procedures supported both from the command line as well as setting +`submodule.<name>.update`: checkout;; the commit recorded in the superproject will be - checked out in the submodule on a detached HEAD. This is - done when `--checkout` option is given, or no option is - given, and `submodule.<name>.update` is unset, or if it is - set to 'checkout'. + checked out in the submodule on a detached HEAD. + If `--force` is specified, the submodule will be checked out (using `git checkout --force` if appropriate), even if the commit specified @@ -173,23 +178,21 @@ in the index of the containing repository already matches the commit checked out in the submodule. rebase;; the current branch of the submodule will be rebased - onto the commit recorded in the superproject. This is done - when `--rebase` option is given, or no option is given, and - `submodule.<name>.update` is set to 'rebase'. + onto the commit recorded in the superproject. merge;; the commit recorded in the superproject will be merged - into the current branch in the submodule. This is done - when `--merge` option is given, or no option is given, and - `submodule.<name>.update` is set to 'merge'. + into the current branch in the submodule. + +The following procedures are only available via the `submodule.<name>.update` +configuration variable: custom command;; arbitrary shell command that takes a single argument (the sha1 of the commit recorded in the - superproject) is executed. This is done when no option is - given, and `submodule.<name>.update` has the form of - '!command'. + superproject) is executed. When `submodule.<name>.update` + is set to '!command', the remainder after the exclamation mark + is the custom command. -When no option is given and `submodule.<name>.update` is set to 'none', -the submodule is not updated. + none;; the submodule is not updated. If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the @@ -198,7 +201,7 @@ submodule with the `--init` option. If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. -- -summary:: +summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]:: Show commit summary between the given commit (defaults to HEAD) and working tree/index. For a submodule in question, a series of commits in the submodule between the given super project commit and the @@ -211,7 +214,7 @@ summary:: Using the `--submodule=log` option with linkgit:git-diff[1] will provide that information too. -foreach:: +foreach [--recursive] <command>:: Evaluates an arbitrary shell command in each checked out submodule. The command has access to the variables $name, $path, $sha1 and $toplevel: @@ -228,11 +231,14 @@ foreach:: the processing to terminate. This can be overridden by adding '|| :' to the end of the command. + -As an example, +git submodule foreach \'echo $path {backtick}git -rev-parse HEAD{backtick}'+ will show the path and currently checked out -commit for each submodule. +As an example, the command below will show the path and currently +checked out commit for each submodule: ++ +-------------- +git submodule foreach 'echo $path `git rev-parse HEAD`' +-------------- -sync:: +sync [--recursive] [--] [<path>...]:: Synchronizes submodules' remote URL configuration setting to the value specified in .gitmodules. It will only affect those submodules which already have a URL entry in .git/config (that is the diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 7386c93162..1579abf3c3 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -163,14 +163,16 @@ may not support it yet. --split-index:: --no-split-index:: - Enable or disable split index mode. If enabled, the index is - split into two files, $GIT_DIR/index and $GIT_DIR/sharedindex.<SHA-1>. - Changes are accumulated in $GIT_DIR/index while the shared - index file contains all index entries stays unchanged. If - split-index mode is already enabled and `--split-index` is - given again, all changes in $GIT_DIR/index are pushed back to - the shared index file. This mode is designed for very large - indexes that take a significant amount of time to read or write. + Enable or disable split index mode. If split-index mode is + already enabled and `--split-index` is given again, all + changes in $GIT_DIR/index are pushed back to the shared index + file. ++ +These options take effect whatever the value of the `core.splitIndex` +configuration variable (see linkgit:git-config[1]). But a warning is +emitted when the change goes against the configured value, as the +configured value will take effect next time the index is read and this +will remove the intended effect of the option. --untracked-cache:: --no-untracked-cache:: @@ -388,6 +390,31 @@ Although this bit looks similar to assume-unchanged bit, its goal is different from assume-unchanged bit's. Skip-worktree also takes precedence over assume-unchanged bit when both are set. +Split index +----------- + +This mode is designed for repositories with very large indexes, and +aims at reducing the time it takes to repeatedly write these indexes. + +In this mode, the index is split into two files, $GIT_DIR/index and +$GIT_DIR/sharedindex.<SHA-1>. Changes are accumulated in +$GIT_DIR/index, the split index, while the shared index file contains +all index entries and stays unchanged. + +All changes in the split index are pushed back to the shared index +file when the number of entries in the split index reaches a level +specified by the splitIndex.maxPercentChange config variable (see +linkgit:git-config[1]). + +Each time a new shared index file is created, the old shared index +files are deleted if their modification time is older than what is +specified by the splitIndex.sharedIndexExpire config variable (see +linkgit:git-config[1]). + +To avoid deleting a shared index file that is still used, its +modification time is updated to the current time everytime a new split +index based on the shared index file is either created or read from. + Untracked cache --------------- diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index e257c19ebe..553cf8413f 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -52,7 +52,7 @@ is linked to the current repository, sharing everything except working 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, +If `<branch>` is omitted and neither `-b` nor `-B` nor `--detach` used, then, as a convenience, a new branch based at HEAD is created automatically, as if `-b $(basename <path>)` was specified. diff --git a/Documentation/git.txt b/Documentation/git.txt index 4f208fab92..3f75af872c 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -44,6 +44,12 @@ 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.12.1/git.html[documentation for release 2.12.1] + +* release notes for + link:RelNotes/2.12.1.txt[2.12.1]. + link:RelNotes/2.12.0.txt[2.12]. + * link:v2.11.1/git.html[documentation for release 2.11.1] * release notes for @@ -1020,6 +1026,12 @@ Usually it is easier to configure any desired options through your personal `.ssh/config` file. Please consult your ssh documentation for further details. +`GIT_SSH_VARIANT`:: + If this environment variable is set, it overrides Git's autodetection + whether `GIT_SSH`/`GIT_SSH_COMMAND`/`core.sshCommand` refer to OpenSSH, + plink or tortoiseplink. This variable overrides the config setting + `ssh.variant` that serves the same purpose. + `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) diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index e0b66c1220..a53d093ca1 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -21,9 +21,11 @@ Each line in `gitattributes` file is of form: pattern attr1 attr2 ... That is, a pattern followed by an attributes list, -separated by whitespaces. When the pattern matches the -path in question, the attributes listed on the line are given to -the path. +separated by whitespaces. Leading and trailing whitespaces are +ignored. Lines that begin with '#' are ignored. Patterns +that begin with a double quote are quoted in C style. +When the pattern matches the path in question, the attributes +listed on the line are given to the path. Each attribute can be in one of these states for a given path: @@ -86,7 +88,7 @@ is either not set or empty, $HOME/.config/git/attributes is used instead. Attributes for all users on a system should be placed in the `$(prefix)/etc/gitattributes` file. -Sometimes you would need to override an setting of an attribute +Sometimes you would need to override a setting of an attribute for a path to `Unspecified` state. This can be done by listing the name of the attribute prefixed with an exclamation point `!`. diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 22309cfb48..3a0ec8c53a 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -1658,4 +1658,4 @@ link:user-manual.html[The Git User's Manual] GIT --- -Part of the linkgit:git[1] suite. +Part of the linkgit:git[1] suite diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt index 4c6143c511..1cd1283d0f 100644 --- a/Documentation/gitcvs-migration.txt +++ b/Documentation/gitcvs-migration.txt @@ -203,4 +203,4 @@ link:user-manual.html[The Git User's Manual] GIT --- -Part of the linkgit:git[1] suite. +Part of the linkgit:git[1] suite diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 08cf62278e..c0a60f3158 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -84,8 +84,8 @@ format sections of the manual for 'git diff-{asterisk}' commands) or diff-patch format. -diffcore-break: For Splitting Up "Complete Rewrites" ----------------------------------------------------- +diffcore-break: For Splitting Up Complete Rewrites +-------------------------------------------------- The second transformation in the chain is diffcore-break, and is controlled by the -B option to the 'git diff-{asterisk}' commands. This is @@ -119,7 +119,7 @@ the original is used), and can be customized by giving a number after "-B" option (e.g. "-B75" to tell it to use 75%). -diffcore-rename: For Detection Renames and Copies +diffcore-rename: For Detecting Renames and Copies ------------------------------------------------- This transformation is used to detect renames and copies, and is @@ -177,8 +177,8 @@ the expense of making it slower. Without `--find-copies-harder`, copied happened to have been modified in the same changeset. -diffcore-merge-broken: For Putting "Complete Rewrites" Back Together --------------------------------------------------------------------- +diffcore-merge-broken: For Putting Complete Rewrites Back Together +------------------------------------------------------------------ This transformation is used to merge filepairs broken by diffcore-break, and not transformed into rename/copy by @@ -288,4 +288,4 @@ link:user-manual.html[The Git User's Manual] GIT --- -Part of the linkgit:git[1] suite. +Part of the linkgit:git[1] suite diff --git a/Documentation/gitglossary.txt b/Documentation/gitglossary.txt index 212e254adc..571f640f5c 100644 --- a/Documentation/gitglossary.txt +++ b/Documentation/gitglossary.txt @@ -24,4 +24,4 @@ link:user-manual.html[The Git User's Manual] GIT --- -Part of the linkgit:git[1] suite. +Part of the linkgit:git[1] suite diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 9e8681f9e1..e4b785eb60 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -452,16 +452,20 @@ set by Git if the remote helper has the 'option' capability. Request the helper to perform a force update. Defaults to 'false'. -'option cloning {'true'|'false'}:: +'option cloning' {'true'|'false'}:: Notify the helper this is a clone request (i.e. the current repository is guaranteed empty). -'option update-shallow {'true'|'false'}:: +'option update-shallow' {'true'|'false'}:: Allow to extend .git/shallow if the new refs require it. -'option pushcert {'true'|'false'}:: +'option pushcert' {'true'|'false'}:: GPG sign pushes. +'option push-option <string>:: + Transmit <string> as a push option. As the a push option + must not contain LF or NUL characters, the string is not encoded. + SEE ALSO -------- linkgit:git-remote[1] diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index a5f99cbb11..f51ed4e37c 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -289,4 +289,4 @@ link:user-manual.html[The Git User's Manual] GIT --- -Part of the linkgit:git[1] suite. +Part of the linkgit:git[1] suite diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index 30d2119565..e0976f6017 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -433,4 +433,4 @@ link:user-manual.html[The Git User's Manual] GIT --- -Part of the linkgit:git[1] suite. +Part of the linkgit:git[1] suite diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index b3b58d324e..794b83393e 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -674,4 +674,4 @@ link:user-manual.html[The Git User's Manual] GIT --- -Part of the linkgit:git[1] suite. +Part of the linkgit:git[1] suite diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index f16c414ea7..177610e44e 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -477,4 +477,4 @@ linkgit:git-am[1] GIT --- -Part of the linkgit:git[1] suite. +Part of the linkgit:git[1] suite diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 8ad29e61a9..6e991c2469 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -384,10 +384,33 @@ full pathname may have special meaning: + Glob magic is incompatible with literal magic. +attr;; +After `attr:` comes a space separated list of "attribute +requirements", all of which must be met in order for the +path to be considered a match; this is in addition to the +usual non-magic pathspec pattern matching. +See linkgit:gitattributes[5]. ++ +Each of the attribute requirements for the path takes one of +these forms: + +- "`ATTR`" requires that the attribute `ATTR` be set. + +- "`-ATTR`" requires that the attribute `ATTR` be unset. + +- "`ATTR=VALUE`" requires that the attribute `ATTR` be + set to the string `VALUE`. + +- "`!ATTR`" requires that the attribute `ATTR` be + unspecified. ++ + exclude;; After a path matches any non-exclude pathspec, it will be run - through all exclude pathspec (magic signature: `!`). If it - matches, the path is ignored. + through all exclude pathspec (magic signature: `!` or its + synonym `^`). If it matches, the path is ignored. When there + is no non-exclude pathspec, the exclusion is applied to the + result set as if invoked without any pathspec. -- [[def_parent]]parent:: diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 5da7cf5a8d..a02f7324c0 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -133,8 +133,8 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit). for all following revision specifiers, up to the next `--not`. --all:: - Pretend as if all the refs in `refs/` are listed on the - command line as '<commit>'. + Pretend as if all the refs in `refs/`, along with `HEAD`, are + listed on the command line as '<commit>'. --branches[=<pattern>]:: Pretend as if all the refs in `refs/heads` are listed diff --git a/Documentation/technical/api-gitattributes.txt b/Documentation/technical/api-gitattributes.txt index 2602668677..e7cbb7c13a 100644 --- a/Documentation/technical/api-gitattributes.txt +++ b/Documentation/technical/api-gitattributes.txt @@ -16,10 +16,15 @@ Data Structure of no interest to the calling programs. The name of the attribute can be retrieved by calling `git_attr_name()`. -`struct git_attr_check`:: +`struct attr_check_item`:: - This structure represents a set of attributes to check in a call - to `git_check_attr()` function, and receives the results. + This structure represents one attribute and its value. + +`struct attr_check`:: + + This structure represents a collection of `attr_check_item`. + It is passed to `git_check_attr()` function, specifying the + attributes to check, and receives their values. Attribute Values @@ -27,7 +32,7 @@ Attribute Values An attribute for a path can be in one of four states: Set, Unset, Unspecified or set to a string, and `.value` member of `struct -git_attr_check` records it. There are three macros to check these: +attr_check_item` records it. There are three macros to check these: `ATTR_TRUE()`:: @@ -48,49 +53,51 @@ value of the attribute for the path. Querying Specific Attributes ---------------------------- -* Prepare an array of `struct git_attr_check` to define the list of - attributes you would want to check. To populate this array, you would - need to define necessary attributes by calling `git_attr()` function. +* Prepare `struct attr_check` using attr_check_initl() + function, enumerating the names of attributes whose values you are + interested in, terminated with a NULL pointer. Alternatively, an + empty `struct attr_check` can be prepared by calling + `attr_check_alloc()` function and then attributes you want to + ask about can be added to it with `attr_check_append()` + function. * Call `git_check_attr()` to check the attributes for the path. -* Inspect `git_attr_check` structure to see how each of the attribute in - the array is defined for the path. +* Inspect `attr_check` structure to see how each of the + attribute in the array is defined for the path. Example ------- -To see how attributes "crlf" and "indent" are set for different paths. +To see how attributes "crlf" and "ident" are set for different paths. -. Prepare an array of `struct git_attr_check` with two elements (because - we are checking two attributes). Initialize their `attr` member with - pointers to `struct git_attr` obtained by calling `git_attr()`: +. Prepare a `struct attr_check` with two elements (because + we are checking two attributes): ------------ -static struct git_attr_check check[2]; +static struct attr_check *check; static void setup_check(void) { - if (check[0].attr) + if (check) return; /* already done */ - check[0].attr = git_attr("crlf"); - check[1].attr = git_attr("ident"); + check = attr_check_initl("crlf", "ident", NULL); } ------------ -. Call `git_check_attr()` with the prepared array of `struct git_attr_check`: +. Call `git_check_attr()` with the prepared `struct attr_check`: ------------ const char *path; setup_check(); - git_check_attr(path, ARRAY_SIZE(check), check); + git_check_attr(path, check); ------------ -. Act on `.value` member of the result, left in `check[]`: +. Act on `.value` member of the result, left in `check->items[]`: ------------ - const char *value = check[0].value; + const char *value = check->items[0].value; if (ATTR_TRUE(value)) { The attribute is Set, by listing only the name of the @@ -109,20 +116,39 @@ static void setup_check(void) } ------------ +To see how attributes in argv[] are set for different paths, only +the first step in the above would be different. + +------------ +static struct attr_check *check; +static void setup_check(const char **argv) +{ + check = attr_check_alloc(); + while (*argv) { + struct git_attr *attr = git_attr(*argv); + attr_check_append(check, attr); + argv++; + } +} +------------ + Querying All Attributes ----------------------- To get the values of all attributes associated with a file: -* Call `git_all_attrs()`, which returns an array of `git_attr_check` - structures. +* Prepare an empty `attr_check` structure by calling + `attr_check_alloc()`. + +* Call `git_all_attrs()`, which populates the `attr_check` + with the attributes attached to the path. -* Iterate over the `git_attr_check` array to examine the attribute - names and values. The name of the attribute described by a - `git_attr_check` object can be retrieved via - `git_attr_name(check[i].attr)`. (Please note that no items will be - returned for unset attributes, so `ATTR_UNSET()` will return false - for all returned `git_array_check` objects.) +* Iterate over the `attr_check.items[]` array to examine + the attribute names and values. The name of the attribute + described by a `attr_check.items[]` object can be retrieved via + `git_attr_name(check->items[i].attr)`. (Please note that no items + will be returned for unset attributes, so `ATTR_UNSET()` will return + false for all returned `attr_check.items[]` objects.) -* Free the `git_array_check` array. +* Free the `attr_check` struct by calling `attr_check_free()`. diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 27bd701c0d..36768b479e 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -168,6 +168,11 @@ There are some macros to easily define options: Introduce an option with string argument. The string argument is put into `str_var`. +`OPT_STRING_LIST(short, long, &struct string_list, arg_str, description)`:: + Introduce an option with string argument. + The string argument is stored as an element in `string_list`. + Use of `--no-option` will clear the list of preceding values. + `OPT_INTEGER(short, long, &int_var, description)`:: Introduce an option with integer argument. The integer is put into `int_var`. |