diff options
Diffstat (limited to 'Documentation')
41 files changed, 1284 insertions, 223 deletions
diff --git a/Documentation/RelNotes/2.13.0.txt b/Documentation/RelNotes/2.13.0.txt new file mode 100644 index 0000000000..b757fd119c --- /dev/null +++ b/Documentation/RelNotes/2.13.0.txt @@ -0,0 +1,559 @@ +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 is now removed. + + * The default location "~/.git-credential-cache/socket" for the + socket used to communicate with the credential-cache daemon has + been moved to "~/.cache/git/credential/socket". + + * Git now avoids blindly falling back to ".git" when the setup + sequence said we are _not_ in Git repository. A corner case that + happens to work right now may be broken by a call to die("BUG"). + We've tried hard to locate such cases and fixed them, but there + might still be cases that need to be addressed--bug reports are + greatly appreciated. + + +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. + + * 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. + + * "git stash push" takes a pathspec so that the local changes can be + stashed away only partially. + + * 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. + + * The command line prompt (in contrib/) learned a new 'tag' style + that can be specified with GIT_PS1_DESCRIBE_STYLE, to describe a + detached HEAD with "git describe --tags". + + * The configuration file learned a new "includeIf.<condition>.path" + that includes the contents of the given path only when the + condition holds. This allows you to say "include this work-related + bit only in the repositories under my ~/work/ directory". + + * Recent update to "rebase -i" started showing a message that is not + a warning with "warning:" prefix by mistake. This has been fixed. + + * Recently we started passing the "--push-options" through the + external remote helper interface; now the "smart HTTP" remote + helper understands what to do with the passed information. + + * "git describe --dirty" dies when it cannot be determined if the + state in the working tree matches that of HEAD (e.g. broken + repository or broken submodule). The command learned a new option + "git describe --broken" to give "$name-broken" (where $name is the + description of HEAD) in such a case. + + * "git checkout" is taught the "--recurse-submodules" option. + + * Recent enhancement to "git stash push" command to support pathspec + to allow only a subset of working tree changes to be stashed away + was found to be too chatty and exposed the internal implementation + detail (e.g. when it uses reset to match the index to HEAD before + doing other things, output from reset seeped out). These, and + other chattyness has been fixed. + + * "git merge <message> HEAD <commit>" syntax that has been deprecated + since October 2007 has been removed. + + * The refs completion for large number of refs has been sped up, + partly by giving up disambiguating ambiguous refs and partly by + eliminating most of the shell processing between 'git for-each-ref' + and 'ls-remote' and Bash's completion facility. + + * On many keyboards, typing "@{" involves holding down SHIFT key and + one can easily end up with "@{Up..." when typing "@{upstream}". As + the upstream/push keywords do not appear anywhere else in the syntax, + we can safely accept them case insensitively without introducing + ambiguity or confusion to solve this. + + * "git tag/branch/for-each-ref" family of commands long allowed to + filter the refs by "--contains X" (show only the refs that are + descendants of X), "--merged X" (show only the refs that are + ancestors of X), "--no-merged X" (show only the refs that are not + ancestors of X). One curious omission, "--no-contains X" (show + only the refs that are not descendants of X) has been added to + them. + + * The default behaviour of "git log" in an interactive session has + been changed to enable "--decorate". + + * The output from "git status --short" has been extended to show + various kinds of dirtyness in submodules differently; instead of to + "M" for modified, 'm' and '?' can be shown to signal changes only + to the working tree of the submodule but not the commit that is + checked out. + + * Allow the http.postbuffer configuration variable to be set to a + size that can be expressed in size_t, which can be larger than + ulong on some platforms. + + +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. + + * A test that creates a confusing branch whose name is HEAD has been + corrected not to do so. + + * The code that parses header fields in the commit object has been + updated for (micro)performance and code hygiene. + + * An helper function to make it easier to append the result from + real_path() to a strbuf has been added. + + * 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. + + * 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. + + * "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. + + * The "debug" helper used in the test framework learned to run + a command under "gdb" interactively. + + * The "detect attempt to create collisions" variant of SHA-1 + implementation by Marc Stevens (CWI) and Dan Shumow (Microsoft) + has been integrated and made the default. + + * The test framework learned to detect unterminated here documents. + + * The name-hash used for detecting paths that are different only in + cases (which matter on case insensitive filesystems) has been + optimized to take advantage of multi-threading when it makes sense. + + * An earlier version of sha1dc/sha1.c that was merged to 'master' + compiled incorrectly on Windows, which has been fixed. + + * "what URL do we want to update this submodule?" and "are we + interested in this submodule?" are split into two distinct + concepts, and then the way used to express the latter got extended, + paving a way to make it easier to manage a project with many + submodules and make it possible to later extend use of multiple + worktrees for a project with submodules. + + * Some debugging output from "git describe" were marked for l10n, + but some weren't. Mark missing ones for l10n. + + * Define a new task in .travis.yml that triggers a test session on + Windows run elsewhere. + + * Conversion from uchar[20] to struct object_id continues. + + * The "submodule" specific field in the ref_store structure is + replaced with a more generic "gitdir" that can later be used also + when dealing with ref_store that represents the set of refs visible + from the other worktrees. + + * The string-list API used a custom reallocation strategy that was + very inefficient, instead of using the usual ALLOC_GROW() macro, + which has been fixed. + (merge 950a234cbd jh/string-list-micro-optim later to maint). + + * In a 2- and 3-way merge of trees, more than one source trees often + end up sharing an identical subtree; optimize by not reading the + same tree multiple times in such a case. + (merge d12a8cf0af jh/unpack-trees-micro-optim later to maint). + + * The index file has a trailing SHA-1 checksum to detect file + corruption, and historically we checked it every time the index + file is used. Omit the validation during normal use, and instead + verify only in "git fsck". + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.12 +----------------- + +Unless otherwise noted, all the fixes since v2.12 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. + + * 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). + + * "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. + + * "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. + + * 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. + + * "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. + + * 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. + + * 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. + + * user.email that consists of only cruft chars should consistently + error out, but didn't. + + * "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. + + * A leak in a codepath to read from a packed object in (rare) cases + has been plugged. + + * 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. + + * 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). + + * A few tests were run conditionally under (rare) conditions where + they cannot be run (like running cvs tests under 'root' account). + + * "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. + + * "git fetch" that requests a commit by object name, when the other + side does not allow such an request, failed without much + explanation. + + * "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. + + * 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. + + * "git push" had a handful of codepaths that could lead to a deadlock + when unexpected error happened, which has been fixed. + + * "Dumb http" transport used to misparse a nonsense http-alternates + response, which has been fixed. + + * "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. + + * "git revert -m 0 $merge_commit" complained that reverting a merge + needs to say relative to which parent the reversion needs to + happen, as if "-m 0" weren't given. The correct diagnosis is that + "-m 0" does not refer to the first parent ("-m 1" does). This has + been fixed. + + * Code to read submodule.<name>.ignore config did not state the + variable name correctly when giving an error message diagnosing + misconfiguration. + + * Fix for NO_PTHREADS build. + + * Fix for potential segv introduced in v2.11.0 and later (also + v2.10.2) to "git log --pickaxe-regex -S". + + * A few unterminated here documents in tests were fixed, which in + turn revealed incorrect expectations the tests make. These tests + have been updated. + + * Fix for NO_PTHREADS option. + (merge 2225e1ea20 bw/grep-recurse-submodules later to maint). + + * Git now avoids blindly falling back to ".git" when the setup + sequence said we are _not_ in Git repository. A corner case that + happens to work right now may be broken by a call to die("BUG"). + (merge b1ef400eec jk/no-looking-at-dotgit-outside-repo-final later to maint). + + * A few commands that recently learned the "--recurse-submodule" + option misbehaved when started from a subdirectory of the + superproject. + (merge b2dfeb7c00 bw/recurse-submodules-relative-fix later to maint). + + * FreeBSD implementation of getcwd(3) behaved differently when an + intermediate directory is unreadable/unsearchable depending on the + length of the buffer provided, which our strbuf_getcwd() was not + aware of. strbuf_getcwd() has been taught to cope with it better. + (merge a54e938e5b rs/freebsd-getcwd-workaround later to maint). + + * A recent update to "rebase -i" stopped running hooks for the "git + commit" command during "reword" action, which has been fixed. + + * Removing an entry from a notes tree and then looking another note + entry from the resulting tree using the internal notes API + functions did not work as expected. No in-tree users of the API + has such access pattern, but it still is worth fixing. + + * "git receive-pack" could have been forced to die by attempting + allocate an unreasonably large amount of memory with a crafted push + certificate; this has been fixed. + (merge f2214dede9 bc/push-cert-receive-fix later to maint). + + * Update error handling for codepath that deals with corrupt loose + objects. + (merge 51054177b3 jk/loose-object-info-report-error later to maint). + + * "git diff --submodule=diff" learned to work better in a project + with a submodule that in turn has its own submodules. + (merge 17b254cda6 sb/show-diff-for-submodule-in-diff-fix later to maint). + + * Update the build dependency so that an update to /usr/bin/perl + etc. result in recomputation of perl.mak file. + (merge c59c4939c2 ab/regen-perl-mak-with-different-perl later to maint). + + * "git push --recurse-submodules --push-option=<string>" learned to + propagate the push option recursively down to pushes in submodules. + + * If a patch e-mail had its first paragraph after an in-body header + indented (even after a blank line after the in-body header line), + the indented line was mistook as a continuation of the in-body + header. This has been fixed. + (merge fd1062e52e lt/mailinfo-in-body-header-continuation later to maint). + + * Clean up fallouts from recent tightening of the set-up sequence, + where Git barfs when repository information is accessed without + first ensuring that it was started in a repository. + (merge bccb22cbb1 jk/no-looking-at-dotgit-outside-repo later to maint). + + * "git p4" used "name-rev HEAD" when it wants to learn what branch is + checked out; it should use "symbolic-ref HEAD". + (merge eff451101d ld/p4-current-branch-fix later to maint). + + * "http.proxy" set to an empty string is used to disable the usage of + proxy. We broke this early last year. + (merge ae51d91105 sr/http-proxy-configuration-fix later to maint). + + * $GIT_DIR may in some cases be normalized with all symlinks resolved + while "gitdir" path expansion in the pattern does not receive the + same treatment, leading to incorrect mismatch. This has been fixed. + + * "git submodule" script does not work well with strange pathnames. + Protect it from a path with slashes in them, at least. + + * "git fetch-pack" was not prepared to accept ERR packet that the + upload-pack can send with a human-readable error message. It + showed the packet contents with ERR prefix, so there was no data + loss, but it was redundant to say "ERR" in an error message. + (merge 8e2c7bef03 jt/fetch-pack-error-reporting later to maint). + + * "ls-files --recurse-submodules" did not quite work well in a + project with nested submodules. + + * gethostname(2) may not NUL terminate the buffer if hostname does + not fit; unfortunately there is no easy way to see if our buffer + was too small, but at least this will make sure we will not end up + using garbage past the end of the buffer. + (merge 5781a9a270 dt/xgethostname-nul-termination later to maint). + + * Other minor doc, test and build updates and code cleanups. + (merge df2a6e38b7 jk/pager-in-use later to maint). + (merge 75ec4a6cb0 ab/branch-list-doc later to maint). + (merge 3e5b36c637 sg/skip-prefix-in-prettify-refname later to maint). + (merge 2c5e2865cc jk/fast-import-cleanup later to maint). + (merge 4473060bc2 ab/test-readme-updates later to maint). + (merge 48a96972fd ab/doc-submitting later to maint). + (merge f5c2bc2b96 jk/make-coccicheck-detect-errors later to maint). + (merge c105f563d1 cc/untracked later to maint). + (merge 8668976b53 jc/unused-symbols later to maint). + (merge fba275dc93 jc/bs-t-is-not-a-tab-for-sed later to maint). + (merge be6ed145de mm/ls-files-s-doc later to maint). + (merge 60b091c679 qp/bisect-docfix later to maint). + (merge 47242cd103 ah/diff-files-ours-theirs-doc later to maint). + (merge 35ad44cbd8 sb/submodule-rm-absorb later to maint). + (merge 0301f1fd92 va/i18n-perl-scripts later to maint). + (merge 733e064d98 vn/revision-shorthand-for-side-branch-log later to maint). + (merge 85999743e7 tb/doc-eol-normalization later to maint). + (merge 0747fb49fd jk/loose-object-fsck later to maint). + (merge d8f4481c4f jk/quarantine-received-objects later to maint). + (merge 7ba1ceef95 xy/format-patch-base later to maint). + (merge fa1912c89a rs/misc-cppcheck-fixes later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 3faf7eb884..bc8ad00473 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -98,12 +98,17 @@ should skip the full stop. It is also conventional in most cases to prefix the first line with "area: " where the area is a filename or identifier for the general area of the code being modified, e.g. - . archive: ustar header checksum is computed unsigned - . git-cherry-pick.txt: clarify the use of revision range notation + . doc: clarify distinction between sign-off and pgp-signing + . githooks.txt: improve the intro section If in doubt which identifier to use, run "git log --no-merges" on the files you are modifying to see the current conventions. +It's customary to start the remainder of the first line after "area: " +with a lower-case letter. E.g. "doc: clarify...", not "doc: +Clarify...", or "githooks.txt: improve...", not "githooks.txt: +Improve...". + The body should provide a meaningful commit message, which: . explains the problem the change tries to solve, iow, what is wrong @@ -129,8 +134,9 @@ with the subject enclosed in a pair of double-quotes, like this: noticed that ... The "Copy commit summary" command of gitk can be used to obtain this -format. +format, or this invocation of "git show": + git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit> (3) Generate your patch using Git tools out of your commits. diff --git a/Documentation/config.txt b/Documentation/config.txt index e43d147825..475e874d51 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 @@ -1925,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. @@ -1960,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 @@ -2835,6 +2918,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 @@ -2905,8 +3013,9 @@ submodule.<name>.url:: The URL for a submodule. This variable is copied from the .gitmodules file to the git config via 'git submodule init'. The user can change the configured URL before obtaining the submodule via 'git submodule - update'. After obtaining the submodule, the presence of this variable - is used as a sign whether the submodule is of interest to git commands. + update'. If neither submodule.<name>.active or submodule.active are + set, the presence of this variable is used as a fallback to indicate + whether the submodule is of interest to git commands. See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details. submodule.<name>.update:: @@ -2944,6 +3053,16 @@ submodule.<name>.ignore:: "--ignore-submodules" option. The 'git submodule' commands are not affected by this setting. +submodule.<name>.active:: + Boolean value indicating if the submodule is of interest to git + commands. This config option takes precedence over the + submodule.active config option. + +submodule.active:: + A repeated field which contains a pathspec used to match against a + submodule's path to determine if the submodule is of interest to git + commands. + submodule.fetchJobs:: Specifies how many submodules are fetched/cloned at the same time. A positive integer allows up to that number of submodules fetched 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-bisect.txt b/Documentation/git-bisect.txt index bdd915a66b..6c42abf070 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -137,7 +137,7 @@ respectively, in place of "good" and "bad". (But note that you cannot mix "good" and "bad" with "old" and "new" in a single session.) In this more general usage, you provide `git bisect` with a "new" -commit has some property and an "old" commit that doesn't have that +commit that has some property and an "old" commit that doesn't have that property. Each time `git bisect` checks out a commit, you test if that commit has the property. If it does, mark the commit as "new"; otherwise, mark it as "old". When the bisection is done, `git bisect` diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 28d46cc03b..81bd0a7b77 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -10,9 +10,10 @@ SYNOPSIS [verse] 'git branch' [--color[=<when>] | --no-color] [-r | -a] [--list] [-v [--abbrev=<length> | --no-abbrev]] - [--column[=<options>] | --no-column] - [(--merged | --no-merged | --contains) [<commit>]] [--sort=<key>] - [--points-at <object>] [<pattern>...] + [--column[=<options>] | --no-column] [--sort=<key>] + [(--merged | --no-merged) [<commit>]] + [--contains [<commit]] [--no-contains [<commit>]] + [--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>] @@ -35,11 +36,12 @@ as branch creation. With `--contains`, shows only the branches that contain the named commit (in other words, the branches whose tip commits are descendants of the -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). +named commit), `--no-contains` inverts it. 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). The command's second form creates a new branch head named <branchname> which points to the current `HEAD`, or <start-point> if given. @@ -142,8 +144,13 @@ This option is only applicable in non-verbose mode. List both remote-tracking branches and local branches. --list:: - Activate the list mode. `git branch <pattern>` would try to create a branch, - use `git branch --list <pattern>` to list matching branches. + List branches. With optional `<pattern>...`, e.g. `git + branch --list 'maint-*'`, list only the branches that match + the pattern(s). ++ +This should not be confused with `git branch -l <branchname>`, +which creates a branch named `<branchname>` with a reflog. +See `--create-reflog` above for details. -v:: -vv:: @@ -213,13 +220,19 @@ start-point is either a local or remote-tracking branch. Only list branches which contain the specified commit (HEAD if not specified). Implies `--list`. +--no-contains [<commit>]:: + Only list branches which don't contain the specified commit + (HEAD if not specified). Implies `--list`. + --merged [<commit>]:: Only list branches whose tips are reachable from the - specified commit (HEAD if not specified). Implies `--list`. + specified commit (HEAD if not specified). Implies `--list`, + incompatible with `--no-merged`. --no-merged [<commit>]:: Only list branches whose tips are not reachable from the - specified commit (HEAD if not specified). Implies `--list`. + specified commit (HEAD if not specified). Implies `--list`, + incompatible with `--merged`. <branchname>:: The name of the branch to create or delete. @@ -253,6 +266,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 -------- @@ -291,13 +309,16 @@ If you are creating a branch that you want to checkout immediately, it is easier to use the git checkout command with its `-b` option to create a branch and check it out with a single command. -The options `--contains`, `--merged` and `--no-merged` serve three related -but different purposes: +The options `--contains`, `--no-contains`, `--merged` and `--no-merged` +serve four related but different purposes: - `--contains <commit>` is used to find all branches which will need special attention if <commit> were to be rebased or amended, since those branches contain the specified <commit>. +- `--no-contains <commit>` is the inverse of that, i.e. branches that don't + contain the specified <commit>. + - `--merged` is used to find all branches which can be safely deleted, since those branches are fully contained by HEAD. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 8e2c0662dd..d6399c0af8 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -256,6 +256,13 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. out anyway. In other words, the ref can be held by more than one worktree. +--[no-]recurse-submodules:: + Using --recurse-submodules will update the content of all initialized + submodules according to the commit recorded in the superproject. If + local modifications in a submodule would be overwritten the checkout + will fail unless `-f` is used. If nothing (or --no-recurse-submodules) + is used, the work trees of submodules will not be updated. + <branch>:: Branch to checkout; if it refers to a branch (i.e., a name that, when prepended with "refs/heads/", is a valid ref), then that diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 35cc34b2fb..30052cce49 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -14,7 +14,7 @@ SYNOPSIS [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] [--dissociate] [--separate-git-dir <git dir>] [--depth <depth>] [--[no-]single-branch] - [--recursive | --recurse-submodules] [--[no-]shallow-submodules] + [--recurse-submodules] [--[no-]shallow-submodules] [--jobs <n>] [--] <repository> [<directory>] DESCRIPTION @@ -215,10 +215,14 @@ objects from the source repository into a pack in the cloned repository. branch when `--single-branch` clone was made, no remote-tracking branch is created. ---recursive:: ---recurse-submodules:: - After the clone is created, initialize all submodules within, - using their default settings. This is equivalent to running +--recurse-submodules[=<pathspec]:: + After the clone is created, initialize and clone submodules + within based on the provided pathspec. If no pathspec is + provided, all submodules are initialized and cloned. + Submodules are initialized and cloned using their default + settings. The resulting clone has `submodule.active` set to + the provided pathspec, or "." (meaning all submodules) if no + pathspec is provided. This is equivalent to running `git submodule update --init --recursive` immediately after the clone is finished. This option is ignored if the cloned repository does not have a worktree/checkout (i.e. if any of diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 2763edb7a7..ed0f5b94b3 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-credential-cache.txt b/Documentation/git-credential-cache.txt index 96208f822e..2b85826393 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -33,10 +33,13 @@ OPTIONS --socket <path>:: Use `<path>` to contact a running cache daemon (or start a new - cache daemon if one is not started). Defaults to - `~/.git-credential-cache/socket`. If your home directory is on a - network-mounted filesystem, you may need to change this to a - local filesystem. You must specify an absolute path. + cache daemon if one is not started). + Defaults to `$XDG_CACHE_HOME/git/credential/socket` unless + `~/.git-credential-cache/` exists in which case + `~/.git-credential-cache/socket` is used instead. + If your home directory is on a network-mounted filesystem, you + may need to change this to a local filesystem. You must specify + an absolute path. CONTROLLING THE DAEMON ---------------------- diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index e4ac448ff5..26f19d3b07 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -30,9 +30,14 @@ OPTIONS Commit-ish object names to describe. Defaults to HEAD if omitted. --dirty[=<mark>]:: - Describe the working tree. - It means describe HEAD and appends <mark> (`-dirty` by - default) if the working tree is dirty. +--broken[=<mark>]:: + Describe the state of the working tree. When the working + tree matches HEAD, the output is the same as "git describe + HEAD". If the working tree has local modification "-dirty" + is appended to it. If a repository is corrupt and Git + cannot determine if there is local modification, Git will + error out, unless `--broken' is given, which appends + the suffix "-broken" instead. --all:: Instead of using only the annotated tags, use any ref @@ -83,7 +88,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-diff.txt b/Documentation/git-diff.txt index bbab35fcaf..b0c1bb95c8 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -97,6 +97,20 @@ OPTIONS :git-diff: 1 include::diff-options.txt[] +-1 --base:: +-2 --ours:: +-3 --theirs:: + Compare the working tree with the "base" version (stage #1), + "our branch" (stage #2) or "their branch" (stage #3). The + index contains these stages only for unmerged entries i.e. + while resolving conflicts. See linkgit:git-read-tree[1] + section "3-Way Merge" for detailed information. + +-0:: + Omit diff output for unmerged entries and just show + "Unmerged". Can be used only when comparing the working tree + with the index. + <path>...:: The <paths> parameters, when given, are used to limit the diff to the named paths (you can give directory diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index abe13f3bed..03e187a105 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -11,7 +11,7 @@ SYNOPSIS 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] [(--sort=<key>)...] [--format=<format>] [<pattern>...] [--points-at <object>] [(--merged | --no-merged) [<object>]] - [--contains [<object>]] + [--contains [<object>]] [--no-contains [<object>]] DESCRIPTION ----------- @@ -69,16 +69,22 @@ OPTIONS --merged [<object>]:: Only list refs whose tips are reachable from the - specified commit (HEAD if not specified). + specified commit (HEAD if not specified), + incompatible with `--no-merged`. --no-merged [<object>]:: Only list refs whose tips are not reachable from the - specified commit (HEAD if not specified). + specified commit (HEAD if not specified), + incompatible with `--merged`. --contains [<object>]:: Only list refs which contain the specified commit (HEAD if not specified). +--no-contains [<object>]:: + Only list refs which don't contain the specified commit (HEAD + if not specified). + --ignore-case:: Sorting and filtering refs are case insensitive. @@ -95,11 +101,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 +125,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 +174,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 +230,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 +325,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-format-patch.txt b/Documentation/git-format-patch.txt index f7a069bb92..c890328b02 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -557,7 +557,7 @@ series A, B, C, the history would be like: ................................................ With `git format-patch --base=P -3 C` (or variants thereof, e.g. with -`--cover-letter` of using `Z..C` instead of `-3 C` to specify the +`--cover-letter` or using `Z..C` instead of `-3 C` to specify the range), the base tree information block is shown at the end of the first message the command outputs (either the first patch, or the cover letter), like this: diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 446209e206..d153c17e06 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -57,7 +57,7 @@ OPTIONS -s:: --stage:: - Show staged contents' object name, mode bits and stage number in the output. + Show staged contents' mode bits, object name and stage number in the output. --directory:: If a whole directory is classified as "other", show just its @@ -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-merge.txt b/Documentation/git-merge.txt index ca3c27b88a..04fdd8cf08 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -13,7 +13,6 @@ SYNOPSIS [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] [--[no-]allow-unrelated-histories] [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...] -'git merge' <msg> HEAD <commit>... 'git merge' --abort 'git merge' --continue @@ -46,11 +45,7 @@ a log message from the user describing the changes. D---E---F---G---H master ------------ -The second syntax (<msg> `HEAD` <commit>...) is supported for -historical reasons. Do not use it from the command line or in -new scripts. It is the same as `git merge -m <msg> <commit>...`. - -The third syntax ("`git merge --abort`") can only be run after the +The second syntax ("`git merge --abort`") can only be run after the merge has resulted in conflicts. 'git merge --abort' will abort the merge process and try to reconstruct the pre-merge state. However, if there were uncommitted changes when the merge started (and 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-read-tree.txt b/Documentation/git-read-tree.txt index fa1d557e5b..ed9d63ef4a 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -115,6 +115,12 @@ OPTIONS directories the index file and index output file are located in. +--[no-]recurse-submodules:: + Using --recurse-submodules will update the content of all initialized + submodules according to the commit recorded in the superproject by + calling read-tree recursively, also setting the submodules HEAD to be + detached at that commit. + --no-sparse-checkout:: Disable sparse checkout support even if `core.sparseCheckout` is true. diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 67d48e6883..53f4e14444 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -370,6 +370,11 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`. of the rebased commits (see linkgit:git-am[1]). Incompatible with the --interactive option. +--signoff:: + This flag is passed to 'git am' to sign off all the rebased + commits (see linkgit:git-am[1]). Incompatible with the + --interactive option. + -i:: --interactive:: Make a list of the commits which are about to be rebased. Let the diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 0ccd5fbc78..86a4b32f0f 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -114,6 +114,8 @@ will be performed, and the update, post-receive and post-update hooks will not be invoked either. This can be useful to quickly bail out if the update is not to be supported. +See the notes on the quarantine environment below. + update Hook ----------- Before each ref is updated, if $GIT_DIR/hooks/update file exists @@ -214,6 +216,33 @@ if the repository is packed and is served via a dumb transport. exec git update-server-info +Quarantine Environment +---------------------- + +When `receive-pack` takes in objects, they are placed into a temporary +"quarantine" directory within the `$GIT_DIR/objects` directory and +migrated into the main object store only after the `pre-receive` hook +has completed. If the push fails before then, the temporary directory is +removed entirely. + +This has a few user-visible effects and caveats: + + 1. Pushes which fail due to problems with the incoming pack, missing + objects, or due to the `pre-receive` hook will not leave any + on-disk data. This is usually helpful to prevent repeated failed + pushes from filling up your disk, but can make debugging more + challenging. + + 2. Any objects created by the `pre-receive` hook will be created in + the quarantine directory (and migrated only if it succeeds). + + 3. The `pre-receive` hook MUST NOT update any refs to point to + quarantined objects. Other programs accessing the repository will + not be able to see the objects (and if the pre-receive hook fails, + those refs would become corrupted). For safety, any ref updates + from within `pre-receive` are automatically rejected. + + SEE ALSO -------- linkgit:git-send-pack[1], linkgit:gitnamespaces[7] 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-send-pack.txt b/Documentation/git-send-pack.txt index a831dd0288..966abb0df8 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -81,6 +81,12 @@ be in a separate packet, and the list must end with a flush packet. will also fail if the actual call to `gpg --sign` fails. See linkgit:git-receive-pack[1] for the details on the receiving end. +--push-option=<string>:: + Pass the specified string as a push option for consumption by + hooks on the server side. If the server doesn't support push + options, error out. See linkgit:git-push[1] and + linkgit:githooks[5] for details. + <host>:: A remote host to house the repository. When this part is specified, 'git-receive-pack' is invoked via diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 2e9e344cd7..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,14 +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 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 _both_ "save" and <message>, but giving - only <message> does not trigger this action to prevent a misspelled - subcommand from making an unwanted stash. + 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..d70abc6afe 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -181,6 +181,17 @@ in which case `XY` are `!!`. ! ! ignored ------------------------------------------------- +Submodules have more state and instead report + M the submodule has a different HEAD than + recorded in the index + m the submodule has modified content + ? the submodule has untracked files +since modified content or untracked files in a submodule cannot be added +via `git add` in the superproject to prepare a commit. + +'m' and '?' are applied recursively. For example if a nested submodule +in a submodule contains an untracked file, this is reported as '?' as well. + If -b is used the short-format status is preceded by a line ## branchname tracking info @@ -210,6 +221,8 @@ field from the first filename). Third, filenames containing special characters are not specially formatted; no quoting or backslash-escaping is performed. +Any submodule changes are reported as modified `M` instead of `m` or single `?`. + Porcelain Format Version 2 ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -322,10 +335,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 8acc72ebb8..74bc6200d5 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -73,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. + @@ -118,18 +122,26 @@ too (and can also report changes to a submodule's work tree). 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. + 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 and submodule.active has been configured, submodules +configured to be active will be initialized, otherwise 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 diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 525737a5d8..f8a0b787f4 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -12,9 +12,10 @@ SYNOPSIS 'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] <tagname> [<commit> | <object>] 'git tag' -d <tagname>... -'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>] - [--column[=<options>] | --no-column] [--create-reflog] [--sort=<key>] - [--format=<format>] [--[no-]merged [<commit>]] [<pattern>...] +'git tag' [-n[<num>]] -l [--contains <commit>] [--contains <commit>] + [--points-at <object>] [--column[=<options>] | --no-column] + [--create-reflog] [--sort=<key>] [--format=<format>] + [--[no-]merged [<commit>]] [<pattern>...] 'git tag' -v [--format=<format>] <tagname>... DESCRIPTION @@ -82,18 +83,24 @@ OPTIONS -n<num>:: <num> specifies how many lines from the annotation, if any, - are printed when using -l. - The default is not to print any annotation lines. - If no number is given to `-n`, only the first line is printed. - If the tag is not annotated, the commit message is displayed instead. - --l <pattern>:: ---list <pattern>:: - List tags with names that match the given pattern (or all if no - pattern is given). Running "git tag" without arguments also - lists all tags. The pattern is a shell wildcard (i.e., matched - using fnmatch(3)). Multiple patterns may be given; if any of - them matches, the tag is shown. + are printed when using -l. Implies `--list`. ++ +The default is not to print any annotation lines. +If no number is given to `-n`, only the first line is printed. +If the tag is not annotated, the commit message is displayed instead. + +-l:: +--list:: + List tags. With optional `<pattern>...`, e.g. `git tag --list + 'v-*'`, list only the tags that match the pattern(s). ++ +Running "git tag" without arguments also lists all tags. The pattern +is a shell wildcard (i.e., matched using fnmatch(3)). Multiple +patterns may be given; if any of them matches, the tag is shown. ++ +This option is implicitly supplied if any other list-like option such +as `--contains` is provided. See the documentation for each of those +options for details. --sort=<key>:: Sort based on the key given. Prefix `-` to sort in @@ -122,10 +129,23 @@ This option is only applicable when listing tags without annotation lines. --contains [<commit>]:: Only list tags which contain the specified commit (HEAD if not - specified). + specified). Implies `--list`. + +--no-contains [<commit>]:: + Only list tags which don't contain the specified commit (HEAD if + not specified). Implies `--list`. + +--merged [<commit>]:: + Only list tags whose commits are reachable from the specified + commit (`HEAD` if not specified), incompatible with `--no-merged`. + +--no-merged [<commit>]:: + Only list tags whose commits are not reachable from the specified + commit (`HEAD` if not specified), incompatible with `--merged`. --points-at <object>:: - Only list tags of the given object. + Only list tags of the given object (HEAD if not + specified). Implies `--list`. -m <msg>:: --message=<msg>:: @@ -173,11 +193,6 @@ This option is only applicable when listing tags without annotation lines. that of linkgit:git-for-each-ref[1]. When unspecified, defaults to `%(refname:strip=2)`. ---[no-]merged [<commit>]:: - Only list tags whose tips are reachable, or not reachable - if `--no-merged` is used, from the specified commit (`HEAD` - if not specified). - CONFIGURATION ------------- By default, 'git tag' in sign-with-default mode (-s) will use your 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.txt b/Documentation/git.txt index 88c39d3ed5..ecc1bb4bd7 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -1027,6 +1027,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..4736483865 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 `!`. @@ -227,11 +229,9 @@ From a clean working directory: ------------------------------------------------- $ echo "* text=auto" >.gitattributes -$ rm .git/index # Remove the index to force Git to -$ git reset # re-scan the working directory +$ rm .git/index # Remove the index to re-scan the working directory +$ git add . $ git status # Show files that will be normalized -$ git add -u -$ git add .gitattributes $ git commit -m "Introduce end-of-line normalization" ------------------------------------------------- diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 9565dc3fda..32343ae295 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -256,6 +256,9 @@ environment variables will not be set. If the client selects to use push options, but doesn't transmit any, the count variable will be set to zero, `GIT_PUSH_OPTION_COUNT=0`. +See the section on "Quarantine Environment" in +linkgit:git-receive-pack[1] for some caveats. + [[update]] update ~~~~~~ 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/revisions.txt b/Documentation/revisions.txt index ba11b9c95e..61277469c8 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -96,7 +96,8 @@ some output processing may assume ref names in UTF-8. refers to the branch that the branch specified by branchname is set to build on top of (configured with `branch.<name>.remote` and `branch.<name>.merge`). A missing branchname defaults to the - current one. + current one. These suffixes are also accepted when spelled in uppercase, and + they mean the same thing no matter the case. '<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: The suffix '@\{push}' reports the branch "where we would push to" if @@ -122,6 +123,9 @@ refs/remotes/myfork/mybranch Note in the example that we set up a triangular workflow, where we pull from one location and push to another. In a non-triangular workflow, '@\{push}' is the same as '@\{upstream}', and there is no need for it. ++ +This suffix is also accepted when spelled in uppercase, and means the same +thing no matter the case. '<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: A suffix '{caret}' to a revision parameter means the first parent of @@ -291,7 +295,7 @@ The 'r1{caret}@' notation means all parents of 'r1'. The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents. By itself, this notation denotes the single commit 'r1'. -The '<rev>{caret}-{<n>}' notation includes '<rev>' but excludes the <n>th +The '<rev>{caret}-<n>' notation includes '<rev>' but excludes the <n>th parent (i.e. a shorthand for '<rev>{caret}<n>..<rev>'), with '<n>' = 1 if not given. This is typically useful for merge commits where you can just pass '<commit>{caret}-' to get all the commits in the branch @@ -333,7 +337,7 @@ Revision Range Summary as giving commit '<rev>' and then all its parents prefixed with '{caret}' to exclude them (and their ancestors). -'<rev>{caret}-{<n>}', e.g. 'HEAD{caret}-, HEAD{caret}-2':: +'<rev>{caret}-<n>', e.g. 'HEAD{caret}-, HEAD{caret}-2':: Equivalent to '<rev>{caret}<n>..<rev>', with '<n>' = 1 if not given. 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-hashmap.txt b/Documentation/technical/api-hashmap.txt index a3f020cd9e..ccc634bbd7 100644 --- a/Documentation/technical/api-hashmap.txt +++ b/Documentation/technical/api-hashmap.txt @@ -21,6 +21,9 @@ that the hashmap is initialized. It may also be useful for statistical purposes `cmpfn` stores the comparison function specified in `hashmap_init()`. In advanced scenarios, it may be useful to change this, e.g. to switch between case-sensitive and case-insensitive lookup. ++ +When `disallow_rehash` is set, automatic rehashes are prevented during inserts +and deletes. `struct hashmap_entry`:: @@ -57,6 +60,7 @@ Functions `unsigned int strihash(const char *buf)`:: `unsigned int memhash(const void *buf, size_t len)`:: `unsigned int memihash(const void *buf, size_t len)`:: +`unsigned int memihash_cont(unsigned int hash_seed, const void *buf, size_t len)`:: Ready-to-use hash functions for strings, using the FNV-1 algorithm (see http://www.isthe.com/chongo/tech/comp/fnv). @@ -65,6 +69,9 @@ Functions `memihash` operate on arbitrary-length memory. + `strihash` and `memihash` are case insensitive versions. ++ +`memihash_cont` is a variant of `memihash` that allows a computation to be +continued with another chunk of data. `unsigned int sha1hash(const unsigned char *sha1)`:: @@ -184,6 +191,21 @@ passed to `hashmap_cmp_fn` to decide whether the entry matches the key. + Returns the removed entry, or NULL if not found. +`void hashmap_disallow_rehash(struct hashmap *map, unsigned value)`:: + + Disallow/allow automatic rehashing of the hashmap during inserts + and deletes. ++ +This is useful if the caller knows that the hashmap will be accessed +by multiple threads. ++ +The caller is still responsible for any necessary locking; this simply +prevents unexpected rehashing. The caller is also responsible for properly +sizing the initial hashmap to ensure good performance. ++ +A call to allow rehashing does not force a rehash; that might happen +with the next insert or delete. + `void hashmap_iter_init(struct hashmap *map, struct hashmap_iter *iter)`:: `void *hashmap_iter_next(struct hashmap_iter *iter)`:: `void *hashmap_iter_first(struct hashmap *map, struct hashmap_iter *iter)`:: diff --git a/Documentation/technical/api-sha1-array.txt b/Documentation/technical/api-oid-array.txt index dcc52943a5..b0c11f868d 100644 --- a/Documentation/technical/api-sha1-array.txt +++ b/Documentation/technical/api-oid-array.txt @@ -1,7 +1,7 @@ -sha1-array API +oid-array API ============== -The sha1-array API provides storage and manipulation of sets of SHA-1 +The oid-array API provides storage and manipulation of sets of object identifiers. The emphasis is on storage and processing efficiency, making them suitable for large lists. Note that the ordering of items is not preserved over some operations. @@ -9,10 +9,10 @@ not preserved over some operations. Data Structures --------------- -`struct sha1_array`:: +`struct oid_array`:: - A single array of SHA-1 hashes. This should be initialized by - assignment from `SHA1_ARRAY_INIT`. The `sha1` member contains + A single array of object IDs. This should be initialized by + assignment from `OID_ARRAY_INIT`. The `oid` member contains the actual data. The `nr` member contains the number of items in the set. The `alloc` and `sorted` members are used internally, and should not be needed by API callers. @@ -20,22 +20,22 @@ Data Structures Functions --------- -`sha1_array_append`:: - Add an item to the set. The sha1 will be placed at the end of +`oid_array_append`:: + Add an item to the set. The object ID will be placed at the end of the array (but note that some operations below may lose this ordering). -`sha1_array_lookup`:: - Perform a binary search of the array for a specific sha1. +`oid_array_lookup`:: + Perform a binary search of the array for a specific object ID. If found, returns the offset (in number of elements) of the - sha1. If not found, returns a negative integer. If the array is - not sorted, this function has the side effect of sorting it. + object ID. If not found, returns a negative integer. If the array + is not sorted, this function has the side effect of sorting it. -`sha1_array_clear`:: +`oid_array_clear`:: Free all memory associated with the array and return it to the initial, empty state. -`sha1_array_for_each_unique`:: +`oid_array_for_each_unique`:: Efficiently iterate over each unique element of the list, executing the callback function for each one. If the array is not sorted, this function has the side effect of sorting it. If @@ -47,25 +47,25 @@ Examples -------- ----------------------------------------- -int print_callback(const unsigned char sha1[20], +int print_callback(const struct object_id *oid, void *data) { - printf("%s\n", sha1_to_hex(sha1)); + printf("%s\n", oid_to_hex(oid)); return 0; /* always continue */ } void some_func(void) { - struct sha1_array hashes = SHA1_ARRAY_INIT; - unsigned char sha1[20]; + struct sha1_array hashes = OID_ARRAY_INIT; + struct object_id oid; /* Read objects into our set */ - while (read_object_from_stdin(sha1)) - sha1_array_append(&hashes, sha1); + while (read_object_from_stdin(oid.hash)) + oid_array_append(&hashes, &oid); /* Check if some objects are in our set */ - while (read_object_from_stdin(sha1)) { - if (sha1_array_lookup(&hashes, sha1) >= 0) + while (read_object_from_stdin(oid.hash)) { + if (oid_array_lookup(&hashes, &oid) >= 0) printf("it's in there!\n"); /* @@ -75,6 +75,6 @@ void some_func(void) * Instead, this will sort once and then skip duplicates * in linear time. */ - sha1_array_for_each_unique(&hashes, print_callback, NULL); + oid_array_for_each_unique(&hashes, print_callback, NULL); } ----------------------------------------- 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`. diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index c59ac9936a..5b0ba3ef20 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -351,14 +351,19 @@ ACK after 'done' if there is at least one common base and multi_ack or multi_ack_detailed is enabled. The server always sends NAK after 'done' if there is no common base found. +Instead of 'ACK' or 'NAK', the server may send an error message (for +example, if it does not recognize an object in a 'want' line received +from the client). + Then the server will start sending its packfile data. ---- - server-response = *ack_multi ack / nak + server-response = *ack_multi ack / nak / error-line ack_multi = PKT-LINE("ACK" SP obj-id ack_status) ack_status = "continue" / "common" / "ready" ack = PKT-LINE("ACK" SP obj-id) nak = PKT-LINE("NAK") + error-line = PKT-LINE("ERR" SP explanation-text) ---- A simple clone may look like this (with no 'have' lines): |