diff options
Diffstat (limited to 'Documentation')
23 files changed, 602 insertions, 64 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index a4191aa388..c4cb5ff0d4 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -24,7 +24,7 @@ code. For Git in general, a few rough rules are: "Once it _is_ in the tree, it's not really worth the patch noise to go and fix it up." - Cf. http://article.gmane.org/gmane.linux.kernel/943020 + Cf. http://lkml.iu.edu/hypermail/linux/kernel/1001.3/01069.html Make your code readable and sensible, and don't try to be clever. @@ -256,12 +256,12 @@ For C programs: Note however that a comment that explains a translatable string to translators uses a convention of starting with a magic token - "TRANSLATORS: " immediately after the opening delimiter, even when - it spans multiple lines. We do not add an asterisk at the beginning - of each line, either. E.g. + "TRANSLATORS: ", e.g. - /* TRANSLATORS: here is a comment that explains the string - to be translated, that follows immediately after it */ + /* + * TRANSLATORS: here is a comment that explains the string to + * be translated, that follows immediately after it. + */ _("Here is a translatable string explained by the above."); - Double negation is often harder to understand than no negation diff --git a/Documentation/RelNotes/2.13.1.txt b/Documentation/RelNotes/2.13.1.txt new file mode 100644 index 0000000000..04c752c490 --- /dev/null +++ b/Documentation/RelNotes/2.13.1.txt @@ -0,0 +1,69 @@ +Git v2.13.1 Release Notes +========================= + +Fixes since v2.13 +----------------- + + * The Web interface to gmane news archive is long gone, even though + the articles are still accessible via NTTP. Replace the links with + ones to public-inbox.org. Because their message identification is + based on the actual message-id, it is likely that it will be easier + to migrate away from it if/when necessary. + + * Update tests to pass under GETTEXT_POISON (a mechanism to ensure + that output strings that should not be translated are not + translated by mistake), and tell TravisCI to run them. + + * Setting "log.decorate=false" in the configuration file did not take + effect in v2.13, which has been corrected. + + * An earlier update to test 7400 needed to be skipped on CYGWIN. + + * Git sometimes gives an advice in a rhetorical question that does + not require an answer, which can confuse new users and non native + speakers. Attempt to rephrase them. + + * "git read-tree -m" (no tree-ish) gave a nonsense suggestion "use + --empty if you want to clear the index". With "-m", such a request + will still fail anyway, as you'd need to name at least one tree-ish + to be merged. + + * The codepath in "git am" that is used when running "git rebase" + leaked memory held for the log message of the commits being rebased. + + * "pack-objects" can stream a slice of an existing packfile out when + the pack bitmap can tell that the reachable objects are all needed + in the output, without inspecting individual objects. This + strategy however would not work well when "--local" and other + options are in use, and need to be disabled. + + * Clarify documentation for include.path and includeIf.<condition>.path + configuration variables. + + * Tag objects, which are not reachable from any ref, that point at + missing objects were mishandled by "git gc" and friends (they + should silently be ignored instead) + + * A few http:// links that are redirected to https:// in the + documentation have been updated to https:// links. + + * Make sure our tests would pass when the sources are checked out + with "platform native" line ending convention by default on + Windows. Some "text" files out tests use and the test scripts + themselves that are meant to be run with /bin/sh, ought to be + checked out with eol=LF even on Windows. + + * Fix memory leaks pointed out by Coverity (and people). + + * The receive-pack program now makes sure that the push certificate + records the same set of push options used for pushing. + + * "git cherry-pick" and other uses of the sequencer machinery + mishandled a trailer block whose last line is an incomplete line. + This has been fixed so that an additional sign-off etc. are added + after completing the existing incomplete line. + + * The shell completion script (in contrib/) learned "git stash" has + a new "push" subcommand. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.14.0.txt b/Documentation/RelNotes/2.14.0.txt new file mode 100644 index 0000000000..1bb29b6e9d --- /dev/null +++ b/Documentation/RelNotes/2.14.0.txt @@ -0,0 +1,321 @@ +Git 2.14 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). + + * 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.13 +------------------- + +UI, Workflows & Features + + * The colors in which "git status --short --branch" showed the names + of the current branch and its remote-tracking branch are now + configurable. + + * "git clone" learned the "--no-tags" option not to fetch all tags + initially, and also set up the tagopt not to follow any tags in + subsequent fetches. + + * "git archive --format=zip" learned to use zip64 extension when + necessary to go beyond the 4GB limit. + (merge 867e40ff3a rs/large-zip later to maint). + + * "git reset" learned "--recurse-submodules" option. + + * "git diff --submodule=diff" now recurses into nested submodules. + (merge 5a5221427c jk/diff-submodule-diff-inline later to maint). + + * "git repack" learned to accept the --threads=<n> option and pass it + to pack-objects. + + * "git send-email" learned to run sendemail-validate hook to inspect + and reject a message before sending it out. + (merge 6489660b4b jt/send-email-validate-hook later to maint). + + * There is no good reason why "git fetch $there $sha1" should fail + when the $sha1 names an object at the tip of an advertised ref, + even when the other side hasn't enabled allowTipSHA1InWant. + + * The recently introduced "[includeIf "gitdir:$dir"] path=..." + mechansim has further been taught to take symlinks into account. + The directory "$dir" specified in "gitdir:$dir" may be a symlink to + a real location, not something that $(getcwd) may return. In such + a case, a realpath of "$dir" is compared with the real path of the + current repository to determine if the contents from the named path + should be included. + + +Performance, Internal Implementation, Development Support etc. + + * The default packed-git limit value has been raised on larger + platforms to save "git fetch" from a (recoverable) failure while + "gc" is running in parallel. + + * Code to update the cache-tree has been tightened so that we won't + accidentally write out any 0{40} entry in the tree object. + (merge a96d3cc3f6 jk/no-null-sha1-in-cache-tree later to maint). + + * Attempt to allow us notice "fishy" situation where we fail to + remove the temporary directory used during the test. + + * Travis CI gained a task to format the documentation with both + AsciiDoc and AsciiDoctor. + (merge 505ad91304 ls/travis-doc-asciidoctor later to maint). + + * Some platforms have ulong that is smaller than time_t, and our + historical use of ulong for timestamp would mean they cannot + represent some timestamp that the platform allows. Invent a + separate and dedicated timestamp_t (so that we can distingiuish + timestamps and a vanilla ulongs, which along is already a good + move), and then declare uintmax_t is the type to be used as the + timestamp_t. + + * We can trigger Windows auto-build tester (credits: Dscho & + Microsoft) from our existing Travis CI tester now. + + * Conversion from uchar[20] to struct object_id continues. + + * Simplify parse_pathspec() codepath and stop it from looking at the + default in-core index. + (merge 08de9151a8 bw/pathspec-sans-the-index later to maint). + + * Add perf-test for wildmatch. + (merge 62ca75a6b9 ab/perf-wildmatch later to maint). + + * Code from "conversion using external process" codepath has been + extracted to a separate sub-process.[ch] module. + (merge 4f2a2e9f0e bp/sub-process-convert-filter later to maint). + + * When "git checkout", "git merge", etc. manipulates the in-core + index, various pieces of information in the index extensions are + discarded from the original state, as it is usually not the case + that they are kept up-to-date and in-sync with the operation on the + main index. The untracked cache extension is copied across these + operations now, which would speed up "git status" (as long as the + cache is properly invalidated). + + * The internal implementation of "git grep" has seen some clean-up. + (merge 8df4c2953f ab/grep-preparatory-cleanup later to maint). + + * Update the C style recommendation for notes for translators, as + recent versions of gettext tools can work with our style of + multi-line comments. + (merge 66f5f6dca9 ab/c-translators-comment-style later to maint). + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.13 +----------------- + +Unless otherwise noted, all the fixes since v2.13 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * "git gc" did not interact well with "git worktree"-managed + per-worktree refs. + + * "git cherry-pick" and other uses of the sequencer machinery + mishandled a trailer block whose last line is an incomplete line. + This has been fixed so that an additional sign-off etc. are added + after completing the existing incomplete line. + (merge 44dc738a39 jt/use-trailer-api-in-commands later to maint). + + * The codepath in "git am" that is used when running "git rebase" + leaked memory held for the log message of the commits being rebased. + (merge 721f5f1e35 jk/am-leakfix later to maint). + + * "git clone --config var=val" is a way to populate the + per-repository configuration file of the new repository, but it did + not work well when val is an empty string. This has been fixed. + (merge db4eca1fea jn/clone-add-empty-config-from-command-line later to maint). + + * Setting "log.decorate=false" in the configuration file did not take + effect in v2.13, which has been corrected. + (merge c74271aae7 ah/log-decorate-default-to-auto later to maint). + + * A few codepaths in "checkout" and "am" working on an unborn branch + tried to access an uninitialized piece of memory. + (merge 57e0ef0e0e rs/checkout-am-fix-unborn later to maint). + + * The Web interface to gmane news archive is long gone, even though + the articles are still accessible via NTTP. Replace the links with + ones to public-inbox.org. Because their message identification is + based on the actual message-id, it is likely that it will be easier + to migrate away from it if/when necessary. + (merge 5840eb9d14 ab/doc-replace-gmane-links later to maint). + + * The receive-pack program now makes sure that the push certificate + records the same set of push options used for pushing. + (merge cbaf82cc6b jt/push-options-doc later to maint). + + * Tests have been updated to pass under GETTEXT_POISON (a mechanism + to ensure that output strings that should not be translated are + not translated by mistake), and TravisCI is told to run them. + (merge b8e188f6f5 ab/fix-poison-tests later to maint). + + * "git checkout --recurse-submodules" did not quite work with a + submodule that itself has submodules. + (merge 218c883783 sb/checkout-recurse-submodules later to maint). + + * Plug some leaks and updates internal API used to implement the + split index feature to make it easier to avoid such a leak in the + future. + (merge de950c5773 nd/split-index-unshare later to maint). + + * "pack-objects" can stream a slice of an existing packfile out when + the pack bitmap can tell that the reachable objects are all needed + in the output, without inspecting individual objects. This + strategy however would not work well when "--local" and other + options are in use, and need to be disabled. + (merge da5a1f8100 jk/disable-pack-reuse-when-broken later to maint). + + * Fix memory leaks pointed out by Coverity (and people). + (merge 443a12f37b js/plug-leaks later to maint). + + * "git read-tree -m" (no tree-ish) gave a nonsense suggestion "use + --empty if you want to clear the index". With "-m", such a request + will still fail anyway, as you'd need to name at least one tree-ish + to be merged. + (merge b9b10d3681 jc/read-tree-empty-with-m later to maint). + + * Make sure our tests would pass when the sources are checked out + with "platform native" line ending convention by default on + Windows. Some "text" files out tests use and the test scripts + themselves that are meant to be run with /bin/sh, ought to be + checked out with eol=LF even on Windows. + (merge 2779f66505 js/eol-on-ourselves later to maint). + + * Introduce the BUG() macro to improve die("BUG: ..."). + (merge 3d7dd2d3b6 jk/bug-to-abort later to maint). + + * Clarify documentation for include.path and includeIf.<condition>.path + configuration variables. + (merge ce933ebd5a jk/doc-config-include later to maint). + + * Git sometimes gives an advice in a rhetorical question that does + not require an answer, which can confuse new users and non native + speakers. Attempt to rephrase them. + (merge 6963893943 ja/do-not-ask-needless-questions later to maint). + + * A few http:// links that are redirected to https:// in the + documentation have been updated to https:// links. + (merge 5e68729fd9 jk/update-links-in-docs later to maint). + + * "git for-each-ref --format=..." with %(HEAD) in the format used to + resolve the HEAD symref as many times as it had processed refs, + which was wasteful, and "git branch" shared the same problem. + (merge 613a0e52ea kn/ref-filter-branch-list later to maint). + + * Regression fix to topic recently merged to 'master'. + (merge d096d7f1ef pw/rebase-i-regression-fix later to maint). + + * The shell completion script (in contrib/) learned "git stash" has + a new "push" subcommand. + (merge 3851e4483f tg/stash-push-fixup later to maint). + + * "git interpret-trailers", when used as GIT_EDITOR for "git commit + -v", looked for and appended to a trailer block at the very end, + i.e. at the end of the "diff" output. The command has been + corrected to pay attention to the cut-mark line "commit -v" adds to + the buffer---the real trailer block should appear just before it. + (merge d76650b8d1 bm/interpret-trailers-cut-line-is-eom later to maint). + + * A test allowed both "git push" and "git receive-pack" on the other + end write their traces into the same file. This is OK on platforms + that allows atomically appending to a file opened with O_APPEND, + but on other platforms led to a mangled output, causing + intermittent test failures. This has been fixed by disabling + traces from "receive-pack" in the test. + (merge 71406ed4d6 jk/alternate-ref-optim later to maint). + + * Tag objects, which are not reachable from any ref, that point at + missing objects were mishandled by "git gc" and friends (they + should silently be ignored instead) + (merge a3ba6bf10a jk/ignore-broken-tags-when-ignoring-missing-links later to maint). + + * "git describe --contains" penalized light-weight tags so much that + they were almost never considered. Instead, give them about the + same chance to be considered as an annotated tag that is the same + age as the underlying commit would. + (merge ef1e74065c jc/name-rev-lw-tag later to maint). + + * The "run-command" API implementation has been made more robust + against dead-locking in a threaded environment. + (merge e3f43ce765 bw/forking-and-threading later to maint). + + * A recent update to t5545-push-options.sh started skipping all the + tests in the script when a web server testing is disabled or + unavailable, not just the ones that require a web server. Non HTTP + tests have been salvaged to always run in this script. + (merge 2e397e4ddf jc/skip-test-in-the-middle later to maint). + + * "git send-email" now uses Net::SMTP::SSL, which is obsolete, only + when needed. Recent versions of Net::SMTP can do TLS natively. + (merge 0ead000c3a dk/send-email-avoid-net-smtp-ssl-when-able later to maint). + + * "foo\bar\baz" in "git fetch foo\bar\baz", even though there is no + slashes in it, cannot be a nickname for a remote on Windows, as + that is likely to be a pathname on a local filesystem. + (merge d9244ecf4f js/bs-is-a-dir-sep-on-windows later to maint). + + * "git clean -d" used to clean directories that has ignored files, + even though the command should not lose ignored ones without "-x". + "git status --ignored" did not list ignored and untracked files + without "-uall". These have been corrected. + (merge 6b1db43109 sl/clean-d-ignored-fix later to maint). + + * The result from "git diff" that compares two blobs, e.g. "git diff + $commit1:$path $commit2:$path", used to be shown with the full + object name as given on the command line, but it is more natural to + use the $path in the output and use it to look up .gitattributes. + (merge 30d005c020 jk/diff-blob later to maint). + + * The "collision detecting" SHA-1 implementation shipped with 2.13 + was quite broken on some big-endian platforms and/or platforms that + do not like unaligned fetches. Update to the upstream code which + has already fixed these issues. + (merge a0103914c2 ab/sha1dc-maint later to maint). + + * "git am -h" triggered a BUG(). + (merge f3a2fffe06 jk/unbreak-am-h later to maint). + + * The interaction of "url.*.insteadOf" and custom URL scheme's + whitelisting is now documented better. + (merge 2c9a2ae285 jk/url-insteadof-config later to maint). + + * Other minor doc, test and build updates and code cleanups. + (merge 515360f9e9 jn/credential-doc-on-clear later to maint). + (merge 0e6d899fee ab/aix-needs-compat-regex later to maint). + (merge e294e8959f jc/apply-fix-mismerge later to maint). + (merge 7f1b225153 bw/submodule-with-bs-path later to maint). + (merge c8f7c8b704 tb/dedup-crlf-tests later to maint). + (merge 449456ad47 sg/core-filemode-doc-typofix later to maint). + (merge ba4dce784e km/log-showsignature-doc later to maint). + (merge c5a9157393 jh/memihash-opt later to maint). + (merge 80f4cd8046 ab/ref-filter-no-contains later to maint). + (merge b275da816c ah/doc-interpret-trailers-ifexists later to maint). + (merge fc7a5edb55 ah/doc-pretty-format-fix later to maint). + (merge 7e95fcb4b5 sb/t5531-update-desc later to maint). + (merge b8f354f294 sd/t3200-typofix later to maint). + (merge ba746ff9c9 ah/doc-filter-branch-export-env later to maint). + (merge 44e2ff09ce ab/t3070-test-dedup later to maint). + (merge 9ee4aa95db rf/completion-config-commit later to maint). + (merge fb87327aee ah/doc-rev-parse-short-default later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index 475e874d51..dd4beec39d 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -79,14 +79,20 @@ escape sequences) are invalid. Includes ~~~~~~~~ +The `include` and `includeIf` sections allow you to include config +directives from another source. These sections behave identically to +each other with the exception that `includeIf` sections may be ignored +if their condition does not evaluate to true; see "Conditional includes" +below. + 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. `include.path` can be given multiple times. +`include.path` (or `includeIf.*.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. These variables can be given multiple times. -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 +The contents of the included file are inserted immediately, as if they +had been found at the location of the include directive. If the value of the +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. @@ -95,8 +101,7 @@ 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. +included. The condition starts with a keyword followed by a colon and some data whose format and meaning depends on the keyword. Supported keywords @@ -140,6 +145,16 @@ A few more notes on matching via `gitdir` and `gitdir/i`: * Symlinks in `$GIT_DIR` are not resolved before matching. + * Both the symlink & realpath versions of paths will be matched + outside of `$GIT_DIR`. E.g. if ~/git is a symlink to + /mnt/storage/git, both `gitdir:~/git` and `gitdir:/mnt/storage/git` + will match. ++ +This was not the case in the initial release of this feature in +v2.13.0, which only matched the realpath version. Configuration that +wants to be compatible with the initial release of this feature needs +to either specify only the realpath version, or both versions. + * Note that "../" is not special and will match literally, which is unlikely what you want. @@ -167,8 +182,8 @@ Example [include] path = /path/to/foo.inc ; include by absolute path - path = foo ; expand "foo" relative to the current file - path = ~/foo ; expand "foo" in your `$HOME` directory + path = foo.inc ; find "foo.inc" relative to the current file + path = ~/foo.inc ; find "foo.inc" in your `$HOME` directory ; include if $GIT_DIR is /path/to/foo/.git [includeIf "gitdir:/path/to/foo/.git"] @@ -182,6 +197,12 @@ Example [includeIf "gitdir:~/to/group/"] path = /path/to/foo.inc + ; relative paths are always relative to the including + ; file (if the condition is true); their location is not + ; affected by the condition + [includeIf "gitdir:/path/to/group/"] + path = foo.inc + Values ~~~~~~ @@ -334,7 +355,7 @@ core.fileMode:: is to be honored. + Some filesystems lose the executable bit when a file that is -marked as executable is checked out, or checks out an +marked as executable is checked out, or checks out a non-executable file with executable bit on. linkgit:git-clone[1] or linkgit:git-init[1] probe the filesystem to see if it handles the executable bit correctly @@ -862,6 +883,7 @@ core.abbrev:: computed based on the approximate number of packed objects in your repository, which hopefully is enough for abbreviated object names to stay unique for some time. + The minimum length is 4. add.ignoreErrors:: add.ignore-errors (deprecated):: @@ -1137,7 +1159,10 @@ color.status.<slot>:: `untracked` (files which are not tracked by Git), `branch` (the current branch), `nobranch` (the color the 'no branch' warning is shown in, defaulting - to red), or + to red), + `localBranch` or `remoteBranch` (the local and remote branch names, + respectively, when branch and tracking information is displayed in the + status short-format), or `unmerged` (files which have unmerged changes). color.ui:: @@ -2140,6 +2165,10 @@ log.showRoot:: Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which normally hide the root commit will now show it. True by default. +log.showSignature:: + If true, makes linkgit:git-log[1], linkgit:git-show[1], and + linkgit:git-whatchanged[1] assume `--show-signature`. + log.mailmap:: If true, makes linkgit:git-log[1], linkgit:git-show[1], and linkgit:git-whatchanged[1] assume `--use-mailmap`. @@ -2620,9 +2649,8 @@ receive.advertiseAtomic:: capability, set this variable to false. receive.advertisePushOptions:: - By default, git-receive-pack will advertise the push options - capability to its clients. If you don't want to advertise this - capability, set this variable to false. + When set to true, git-receive-pack will advertise the push options + capability to its clients. False by default. receive.autogc:: By default, git-receive-pack will run "git-gc --auto" after @@ -3208,6 +3236,13 @@ url.<base>.insteadOf:: the best alternative for the particular user, even for a never-before-seen repository on the site. When more than one insteadOf strings match a given URL, the longest match is used. ++ +Note that any protocol restrictions will be applied to the rewritten +URL. If the rewrite changes the URL to use a custom protocol or remote +helper, you may need to adjust the `protocol.*.allow` config to permit +the request. In particular, protocols you expect to use for submodules +must be set to `always` rather than the default of `user`. See the +description of `protocol.allow` above. url.<base>.pushInsteadOf:: Any URL that starts with this value will not be pushed to; diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index 8ac75fcc25..78479b003e 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -1350,9 +1350,9 @@ References - [[[1]]] https://www.nist.gov/sites/default/files/documents/director/planning/report02-3.pdf['The Economic Impacts of Inadequate Infratructure for Software Testing'. Nist Planning Report 02-3], see Executive Summary and Chapter 8. - [[[2]]] http://www.oracle.com/technetwork/java/codeconvtoc-136057.html['Code Conventions for the Java Programming Language'. Sun Microsystems.] - [[[3]]] https://en.wikipedia.org/wiki/Software_maintenance['Software maintenance'. Wikipedia.] -- [[[4]]] http://article.gmane.org/gmane.comp.version-control.git/45195/[Junio C Hamano. 'Automated bisect success story'. Gmane.] +- [[[4]]] https://public-inbox.org/git/7vps5xsbwp.fsf_-_@assigned-by-dhcp.cox.net/[Junio C Hamano. 'Automated bisect success story'.] - [[[5]]] https://lwn.net/Articles/317154/[Christian Couder. 'Fully automated bisecting with "git bisect run"'. LWN.net.] - [[[6]]] https://lwn.net/Articles/277872/[Jonathan Corbet. 'Bisection divides users and developers'. LWN.net.] -- [[[7]]] http://article.gmane.org/gmane.linux.scsi/36652/[Ingo Molnar. 'Re: BUG 2.6.23-rc3 can't see sd partitions on Alpha'. Gmane.] +- [[[7]]] http://marc.info/?l=linux-kernel&m=119702753411680&w=2[Ingo Molnar. 'Re: BUG 2.6.23-rc3 can't see sd partitions on Alpha'. Linux-kernel mailing list.] - [[[8]]] https://www.kernel.org/pub/software/scm/git/docs/git-bisect.html[Junio C Hamano and the git-list. 'git-bisect(1) Manual Page'. Linux Kernel Archives.] - [[[9]]] https://github.com/Ealdwulf/bbchop[Ealdwulf. 'bbchop'. GitHub.] diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 30052cce49..83c8e9b394 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -13,7 +13,7 @@ SYNOPSIS [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] [--dissociate] [--separate-git-dir <git dir>] - [--depth <depth>] [--[no-]single-branch] + [--depth <depth>] [--[no-]single-branch] [--no-tags] [--recurse-submodules] [--[no-]shallow-submodules] [--jobs <n>] [--] <repository> [<directory>] @@ -215,6 +215,18 @@ 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. +--no-tags:: + Don't clone any tags, and set + `remote.<remote>.tagOpt=--no-tags` in the config, ensuring + that future `git pull` and `git fetch` operations won't follow + any tags. Subsequent explicit tag fetches will still work, + (see linkgit:git-fetch[1]). ++ +Can be used in conjunction with `--single-branch` to clone and +maintain a branch with no references other than a single cloned +branch. This is useful e.g. to maintain minimal clones of the default +branch of some repository for search indexing. + --recurse-submodules[=<pathspec]:: After the clone is created, initialize and clone submodules within based on the provided pathspec. If no pathspec is diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 6e4bb02204..7b695dbb72 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -86,8 +86,7 @@ OPTIONS This filter may be used if you only need to modify the environment in which the commit will be performed. Specifically, you might want to rewrite the author/committer name/email/time environment - variables (see linkgit:git-commit-tree[1] for details). Do not forget - to re-export the variables. + variables (see linkgit:git-commit-tree[1] for details). --tree-filter <command>:: This is the filter for rewriting the tree and its contents. @@ -340,12 +339,10 @@ git filter-branch --env-filter ' if test "$GIT_AUTHOR_EMAIL" = "root@localhost" then GIT_AUTHOR_EMAIL=john@example.com - export GIT_AUTHOR_EMAIL fi if test "$GIT_COMMITTER_EMAIL" = "root@localhost" then GIT_COMMITTER_EMAIL=john@example.com - export GIT_COMMITTER_EMAIL fi ' -- --all -------------------------------------------------------- diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 71f32f3508..5033483db4 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -161,8 +161,11 @@ OPTIONS -P:: --perl-regexp:: - Use Perl-compatible regexp for patterns. Requires libpcre to be - compiled in. + Use Perl-compatible regular expressions for patterns. ++ +Support for these types of regular expressions is an optional +compile-time dependency. If Git wasn't compiled with support for them +providing this option will cause it to die. -F:: --fixed-strings:: diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index 09074c75a4..31cdeaecdf 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -123,7 +123,7 @@ trailer.ifexists:: same <token> in the message. + The valid values for this option are: `addIfDifferentNeighbor` (this -is the default), `addIfDifferent`, `add`, `overwrite` or `doNothing`. +is the default), `addIfDifferent`, `add`, `replace` or `doNothing`. + With `addIfDifferentNeighbor`, a new trailer will be added only if no trailer with the same (<token>, <value>) pair is above or below the line diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index ed9d63ef4a..02576d8c0a 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -137,7 +137,7 @@ Merging ------- If `-m` is specified, 'git read-tree' can perform 3 kinds of merge, a single tree merge if only 1 tree is given, a -fast-forward merge with 2 trees, or a 3-way merge if 3 trees are +fast-forward merge with 2 trees, or a 3-way merge if 3 or more trees are provided. diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 26afe6ed54..ae750e9e11 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -9,7 +9,7 @@ git-repack - Pack unpacked objects in a repository SYNOPSIS -------- [verse] -'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [--window=<n>] [--depth=<n>] +'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [--window=<n>] [--depth=<n>] [--threads=<n>] DESCRIPTION ----------- @@ -92,6 +92,9 @@ other objects in that pack they already have locally. to be applied that many times to get to the necessary object. The default value for --window is 10 and --depth is 50. +--threads=<n>:: + This option is passed through to `git pack-objects`. + --window-memory=<n>:: This option provides an additional limit on top of `--window`; the window size will dynamically scale down so as to not take diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index c40c470448..b1293f24bb 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -126,6 +126,12 @@ can be used. 'git diff-{asterisk}'). In contrast to the `--sq-quote` option, the command input is still interpreted as usual. +--short[=length]:: + Same as `--verify` but shortens the object name to a unique + prefix with at least `length` characters. The minimum length + is 4, the default is the effective value of the `core.abbrev` + configuration variable (see linkgit:git-config[1]). + --not:: When showing object names, prefix them with '{caret}' and strip '{caret}' prefix from the object names that already have @@ -136,12 +142,6 @@ can be used. The option core.warnAmbiguousRefs is used to select the strict abbreviation mode. ---short:: ---short=number:: - Instead of outputting the full SHA-1 values of object names try to - abbreviate them to a shorter unique name. When no length is specified - 7 is used. The minimum length is 4. - --symbolic:: Usually the object names are output in SHA-1 form (with possible '{caret}' prefix); this option makes them output in a diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 9d66166f69..bb23b02caf 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -377,6 +377,7 @@ have been specified, in which case default to 'compose'. Currently, validation means the following: + -- + * Invoke the sendemail-validate hook if present (see linkgit:githooks[5]). * Warn of patches that contain lines longer than 998 characters; this is due to SMTP limits as described by http://www.ietf.org/rfc/rfc2821.txt. -- diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index f8a0b787f4..1eb15afa1c 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -12,7 +12,7 @@ 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>] [--contains <commit>] +'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>] [--points-at <object>] [--column[=<options>] | --no-column] [--create-reflog] [--sort=<key>] [--format=<format>] [--[no-]merged [<commit>]] [<pattern>...] diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index f3a75d1ce1..f970196bc1 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -101,16 +101,6 @@ $ git help credential-foo $ git config --global credential.helper foo ------------------------------------------- -If there are multiple instances of the `credential.helper` configuration -variable, each helper will be tried in turn, and may provide a username, -password, or nothing. Once Git has acquired both a username and a -password, no more helpers will be tried. - -If `credential.helper` is configured to the empty string, this resets -the helper list to empty (so you may override a helper set by a -lower-priority config file by configuring the empty-string helper, -followed by whatever set of helpers you would like). - CREDENTIAL CONTEXTS ------------------- @@ -162,6 +152,16 @@ helper:: shell (so, for example, setting this to `foo --option=bar` will execute `git credential-foo --option=bar` via the shell. See the manual of specific helpers for examples of their use. ++ +If there are multiple instances of the `credential.helper` configuration +variable, each helper will be tried in turn, and may provide a username, +password, or nothing. Once Git has acquired both a username and a +password, no more helpers will be tried. ++ +If `credential.helper` is configured to the empty string, this resets +the helper list to empty (so you may override a helper set by a +lower-priority config file by configuring the empty-string helper, +followed by whatever set of helpers you would like). username:: diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 706091a569..b2514f4d44 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -447,6 +447,14 @@ rebase:: The commits are guaranteed to be listed in the order that they were processed by rebase. +sendemail-validate +~~~~~~~~~~~~~~~~~~ + +This hook is invoked by 'git send-email'. It takes a single parameter, +the name of the file that holds the e-mail to be sent. Exiting with a +non-zero status causes 'git send-email' to abort before sending any +e-mails. + GIT --- diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt index 96156e5e1f..88450589af 100644 --- a/Documentation/gitweb.txt +++ b/Documentation/gitweb.txt @@ -84,7 +84,7 @@ separator (rules for Perl's "`split(" ", $line)`"). * Fields use modified URI encoding, defined in RFC 3986, section 2.1 (Percent-Encoding), or rather "Query string encoding" (see -http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference +https://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference being that SP (" ") can be encoded as "{plus}" (and therefore "{plus}" has to be also percent-encoded). + diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 47b286b33e..38040e95b5 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -199,7 +199,7 @@ endif::git-rev-list[] than given and there are spaces on its left, use those spaces - '%><(<N>)', '%><|(<N>)': similar to '% <(<N>)', '%<|(<N>)' respectively, but padding both sides (i.e. the text is centered) --%(trailers): display the trailers of the body as interpreted by +- %(trailers): display the trailers of the body as interpreted by linkgit:git-interpret-trailers[1] NOTE: Some placeholders may depend on other options given to the diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index a02f7324c0..a46f70c2b1 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -92,8 +92,12 @@ endif::git-rev-list[] pattern as a regular expression). --perl-regexp:: - Consider the limiting patterns to be Perl-compatible regular expressions. - Requires libpcre to be compiled in. + Consider the limiting patterns to be Perl-compatible regular + expressions. ++ +Support for these types of regular expressions is an optional +compile-time dependency. If Git wasn't compiled with support for them +providing this option will cause it to die. --remove-empty:: Stop when a given path disappears from the tree. diff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt index 7f8e78d916..6c77b4920c 100644 --- a/Documentation/technical/api-directory-listing.txt +++ b/Documentation/technical/api-directory-listing.txt @@ -33,6 +33,12 @@ The notable options are: Similar to `DIR_SHOW_IGNORED`, but return ignored files in `ignored[]` in addition to untracked files in `entries[]`. +`DIR_KEEP_UNTRACKED_CONTENTS`::: + + Only has meaning if `DIR_SHOW_IGNORED_TOO` is also set; if this is set, the + untracked contents of untracked directories are also returned in + `entries[]`. + `DIR_COLLECT_IGNORED`::: Special mode for git-add. Return ignored files in `ignored[]` and diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 36768b479e..829b558110 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -183,13 +183,13 @@ There are some macros to easily define options: scale the provided value by 1024, 1024^2 or 1024^3 respectively. The scaled value is put into `unsigned_long_var`. -`OPT_DATE(short, long, &int_var, description)`:: +`OPT_DATE(short, long, ×tamp_t_var, description)`:: Introduce an option with date argument, see `approxidate()`. - The timestamp is put into `int_var`. + The timestamp is put into `timestamp_t_var`. -`OPT_EXPIRY_DATE(short, long, &int_var, description)`:: +`OPT_EXPIRY_DATE(short, long, ×tamp_t_var, description)`:: Introduce an option with expiry date argument, see `parse_expiry_date()`. - The timestamp is put into `int_var`. + The timestamp is put into `timestamp_t_var`. `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`:: Introduce an option with argument. diff --git a/Documentation/technical/api-sub-process.txt b/Documentation/technical/api-sub-process.txt new file mode 100644 index 0000000000..793508cf3e --- /dev/null +++ b/Documentation/technical/api-sub-process.txt @@ -0,0 +1,59 @@ +sub-process API +=============== + +The sub-process API makes it possible to run background sub-processes +for the entire lifetime of a Git invocation. If Git needs to communicate +with an external process multiple times, then this can reduces the process +invocation overhead. Git and the sub-process communicate through stdin and +stdout. + +The sub-processes are kept in a hashmap by command name and looked up +via the subprocess_find_entry function. If an existing instance can not +be found then a new process should be created and started. When the +parent git command terminates, all sub-processes are also terminated. + +This API is based on the run-command API. + +Data structures +--------------- + +* `struct subprocess_entry` + +The sub-process structure. Members should not be accessed directly. + +Types +----- + +'int(*subprocess_start_fn)(struct subprocess_entry *entry)':: + + User-supplied function to initialize the sub-process. This is + typically used to negotiate the interface version and capabilities. + + +Functions +--------- + +`cmd2process_cmp`:: + + Function to test two subprocess hashmap entries for equality. + +`subprocess_start`:: + + Start a subprocess and add it to the subprocess hashmap. + +`subprocess_stop`:: + + Kill a subprocess and remove it from the subprocess hashmap. + +`subprocess_find_entry`:: + + Find a subprocess in the subprocess hashmap. + +`subprocess_get_child_process`:: + + Get the underlying `struct child_process` from a subprocess. + +`subprocess_read_status`:: + + Helper function to read packets looking for the last "status=<foo>" + key/value pair. diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 5b0ba3ef20..a34917153f 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -473,13 +473,10 @@ that it wants to update, it sends a line listing the obj-id currently on the server, the obj-id the client would like to update it to and the name of the reference. -This list is followed by a flush-pkt. Then the push options are transmitted -one per packet followed by another flush-pkt. After that the packfile that -should contain all the objects that the server will need to complete the new -references will be sent. +This list is followed by a flush-pkt. ---- - update-request = *shallow ( command-list | push-cert ) [packfile] + update-requests = *shallow ( command-list | push-cert ) shallow = PKT-LINE("shallow" SP obj-id) @@ -500,12 +497,35 @@ references will be sent. PKT-LINE("pusher" SP ident LF) PKT-LINE("pushee" SP url LF) PKT-LINE("nonce" SP nonce LF) + *PKT-LINE("push-option" SP push-option LF) PKT-LINE(LF) *PKT-LINE(command LF) *PKT-LINE(gpg-signature-lines LF) PKT-LINE("push-cert-end" LF) - packfile = "PACK" 28*(OCTET) + push-option = 1*( VCHAR | SP ) +---- + +If the server has advertised the 'push-options' capability and the client has +specified 'push-options' as part of the capability list above, the client then +sends its push options followed by a flush-pkt. + +---- + push-options = *PKT-LINE(push-option) flush-pkt +---- + +For backwards compatibility with older Git servers, if the client sends a push +cert and push options, it MUST send its push options both embedded within the +push cert and after the push cert. (Note that the push options within the cert +are prefixed, but the push options after the cert are not.) Both these lists +MUST be the same, modulo the prefix. + +After that the packfile that +should contain all the objects that the server will need to complete the new +references will be sent. + +---- + packfile = "PACK" 28*(OCTET) ---- If the receiving end does not support delete-refs, the sending end MUST |