diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/2.14.2.txt | 35 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.15.0.txt | 220 | ||||
| -rw-r--r-- | Documentation/config.txt | 10 | ||||
| -rw-r--r-- | Documentation/diff-config.txt | 11 | ||||
| -rw-r--r-- | Documentation/diff-options.txt | 17 | ||||
| -rw-r--r-- | Documentation/git-branch.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-for-each-ref.txt | 15 | ||||
| -rw-r--r-- | Documentation/git-format-patch.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-grep.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-merge.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-push.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-send-pack.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-tag.txt | 7 | ||||
| -rw-r--r-- | Documentation/git.txt | 3 | ||||
| -rw-r--r-- | Documentation/gitattributes.txt | 69 | ||||
| -rw-r--r-- | Documentation/githooks.txt | 4 | ||||
| -rw-r--r-- | Documentation/pretty-formats.txt | 18 | ||||
| -rw-r--r-- | Documentation/technical/api-builtin.txt | 73 | ||||
| -rw-r--r-- | Documentation/technical/api-config.txt | 4 | ||||
| -rw-r--r-- | Documentation/technical/api-sub-process.txt | 59 | ||||
| -rw-r--r-- | Documentation/technical/api-tree-walking.txt | 6 |
21 files changed, 394 insertions, 188 deletions
diff --git a/Documentation/RelNotes/2.14.2.txt b/Documentation/RelNotes/2.14.2.txt new file mode 100644 index 0000000000..5517afcf59 --- /dev/null +++ b/Documentation/RelNotes/2.14.2.txt @@ -0,0 +1,35 @@ +Git v2.14.2 Release Notes +========================= + +Fixes since v2.14.1 +------------------- + + * Because recent Git for Windows do come with a real msgfmt, the + build procedure for git-gui has been updated to use it instead of a + hand-rolled substitute. + + * "%C(color name)" in the pretty print format always produced ANSI + color escape codes, which was an early design mistake. They now + honor the configuration (e.g. "color.ui = never") and also tty-ness + of the output medium. + + * The http.{sslkey,sslCert} configuration variables are to be + interpreted as a pathname that honors "~[username]/" prefix, but + weren't, which has been fixed. + + * Numerous bugs in walking of reflogs via "log -g" and friends have + been fixed. + + * "git commit" when seeing an totally empty message said "you did not + edit the message", which is clearly wrong. The message has been + corrected. + + * When a directory is not readable, "gitweb" fails to build the + project list. Work this around by skipping such a directory. + + * A recently added test for the "credential-cache" helper revealed + that EOF detection done around the time the connection to the cache + daemon is torn down were flaky. This was fixed by reacting to + ECONNRESET and behaving as if we got an EOF. + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.15.0.txt b/Documentation/RelNotes/2.15.0.txt new file mode 100644 index 0000000000..2fd49978d7 --- /dev/null +++ b/Documentation/RelNotes/2.15.0.txt @@ -0,0 +1,220 @@ +Git 2.15 Release Notes +====================== + +Backward compatibility notes and other notable changes. + + * 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 now scheduled to happen in the upcoming + release. + + * 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.14 +------------------- + +UI, Workflows & Features + + * An example that is now obsolete has been removed from a sample hook, + and an old example in it that added a sign-off manually has been + improved to use the interpret-trailers command. + + * The advice message given when "git rebase" stops for conflicting + changes has been improved. + + * The "rerere-train" script (in contrib/) learned the "--overwrite" + option to allow overwriting existing recorded resolutions. + (merge ad53bf79aa rg/rerere-train-overwrite later to maint). + + * "git contacts" (in contrib/) now lists the address on the + "Reported-by:" trailer to its output, in addition to those on + S-o-b: and other trailers, to make it easier to notify (and thank) + the original bug reporter. + (merge 09ac673788 eb/contacts-reported-by later to maint). + + * "git rebase", especially when it is run by mistake and ends up + trying to replay many changes, spent long time in silence. The + command has been taught to show progress report when it spends + long time preparing these many changes to replay (which would give + the user a chance to abort with ^C). + + +Performance, Internal Implementation, Development Support etc. + + * Conversion from uchar[20] to struct object_id continues. + + * Start using selected c99 constructs in small, stable and + essentialpart of the system to catch people who care about + older compilers that do not grok them. + + * The filter-process interface learned to allow a process with long + latency give a "delayed" response. + + * Many uses of comparision callback function the hashmap API uses + cast the callback function type when registering it to + hashmap_init(), which defeats the compile time type checking when + the callback interface changes (e.g. gaining more parameters). + The callback implementations have been updated to take "void *" + pointers and cast them to the type they expect instead. + + * Because recent Git for Windows do come with a real msgfmt, the + build procedure for git-gui has been updated to use it instead of a + hand-rolled substitute. + (merge 90dbf226ba js/git-gui-msgfmt-on-windows later to maint). + + * "git grep --recurse-submodules" has been reworked to give a more + consistent output across submodule boundary (and do its thing + without having to fork a separate process). + + * A helper function to read a single whole line into strbuf + mistakenly triggered OOM error at EOF under certain conditions, + which has been fixed. + (merge 642956cf45 rs/strbuf-getwholeline-fix later to maint). + + * The "ref-store" code reorganization continues. + + * "git commit" used to discard the index and re-read from the filesystem + just in case the pre-commit hook has updated it in the middle; this + has been optimized out when we know we do not run the pre-commit hook. + (merge 680ee550d7 kw/commit-keep-index-when-pre-commit-is-not-run later to maint). + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.14 +----------------- + + * "%C(color name)" in the pretty print format always produced ANSI + color escape codes, which was an early design mistake. They now + honor the configuration (e.g. "color.ui = never") and also tty-ness + of the output medium. + (merge 11b087adfd jk/ref-filter-colors later to maint). + + * The http.{sslkey,sslCert} configuration variables are to be + interpreted as a pathname that honors "~[username]/" prefix, but + weren't, which has been fixed. + (merge 8d1549643e jc/http-sslkey-and-ssl-cert-are-paths later to maint). + + * Numerous bugs in walking of reflogs via "log -g" and friends have + been fixed. + (merge de239446b6 jk/reflog-walk later to maint). + + * "git commit" when seeing an totally empty message said "you did not + edit the message", which is clearly wrong. The message has been + corrected. + (merge bc17f35f8c ks/commit-abort-on-empty-message-fix later to maint). + + * When a directory is not readable, "gitweb" fails to build the + project list. Work this around by skipping such a directory. + (merge 46a13857fc hb/gitweb-project-list later to maint). + + * Some versions of GnuPG fails to kill gpg-agent it auto-spawned + and such a left-over agent can interfere with a test. Work it + around by attempting to kill one before starting a new test. + (merge 29ff1f8f74 st/lib-gpg-kill-stray-agent later to maint). + + * A recently added test for the "credential-cache" helper revealed + that EOF detection done around the time the connection to the cache + daemon is torn down were flaky. This was fixed by reacting to + ECONNRESET and behaving as if we got an EOF. + (merge 1f180e5eb9 dl/credential-cache-socket-in-xdg-cache later to maint). + + * "git log --tag=no-such-tag" showed log starting from HEAD, which + has been fixed---it now shows nothing. + (merge 5d34d1ac06 jk/rev-list-empty-input later to maint). + + * The "tag.pager" configuration variable was useless for those who + actually create tag objects, as it interfered with the use of an + editor. A new mechanism has been introduced for commands to enable + pager depending on what operation is being carried out to fix this, + and then "git tag -l" is made to run pager by default. + (merge 595d59e2b5 ma/pager-per-subcommand-action later to maint). + + * "git push --recurse-submodules $there HEAD:$target" was not + propagated down to the submodules, but now it is. + (merge c7be7201a7 bw/push-options-recursively-to-submodules later to maint). + + * Commands like "git rebase" accepted the --rerere-autoupdate option + from the command line, but did not always use it. This has been + fixed. + (merge f826fb799e pw/sequence-rerere-autoupdate later to maint). + + * "git clone --recurse-submodules --quiet" did not pass the quiet + option down to submodules. + (merge 03c004c581 bw/clone-recursive-quiet later to maint). + + * Test portability fix for OBSD. + (merge bed67874e2 rs/obsd-getcwd-workaround later to maint). + (merge 4c7fda8fc1 rs/t4062-obsd later to maint). + + * Portability fix for OBSD. + (merge 29c2eda80b rs/in-obsd-basename-dirname-take-const later to maint). + + * "git am -s" has been taught that some input may end with a trailer + block that is not Signed-off-by: and it should refrain from adding + an extra blank line before adding a new sign-off in such a case. + (merge 735285b403 pw/am-signoff later to maint). + + * "git svn" used with "--localtime" option did not compute the tz + offset for the timestamp in question and instead always used the + current time, which has been corrected. + (merge 1adc4b9a58 ur/svn-local-zone later to maint). + + * Memory leak in an error codepath has been plugged. + (merge 83cd6f9017 rs/fsck-obj-leakfix later to maint). + (merge 896dca3ab7 rs/unpack-entry-leakfix later to maint). + (merge 149d8cbb2e rs/win32-syslog-leakfix later to maint). + + * "git stash -u" used the contents of the committed version of the + ".gitignore" file to decide which paths are ignored, even when the + file has local changes. The command has been taught to instead use + the locally modified contents. + + * bash 4.4 or newer gave a warning on NUL byte in command + substitution done in "git stash"; this has been squelched. + (merge 5fc92f8828 kd/stash-with-bash-4.4 later to maint). + + * "git grep -L" and "git grep --quiet -L" reported different exit + codes; this has been corrected. + (merge e1f68c66d5 as/grep-quiet-no-match-exit-code-fix later to maint). + + * Other minor doc, test and build updates and code cleanups. + (merge 5b114f3bb0 rs/bswap-ubsan-fix later to maint). + (merge 168e63554c rs/move-array later to maint). + (merge 268ba20110 rs/stat-data-unaligned-reads-fix later to maint). + (merge 78e7b98f45 jt/fsck-code-cleanup later to maint). + (merge c7b0780545 rs/pack-objects-pbase-cleanup later to maint). + (merge c1e860f1dc js/run-process-parallel-api-fix later to maint). + (merge 7a40a95eb4 cc/ref-is-hidden-microcleanup later to maint). + (merge c0bb6d9cef ah/doc-wserrorhighlight later to maint). + (merge edd64ef4f7 dc/fmt-merge-msg-microcleanup later to maint). + (merge fa64a2fdbe jt/subprocess-handshake later to maint). + (merge 0ba9c9a0fb jb/t8008-cleanup later to maint). + (merge a7c28a2161 jt/t1450-fsck-corrupt-packfile later to maint). + (merge dff2813391 ab/ref-filter-no-contains later to maint). + (merge f094b89a4d ma/parse-maybe-bool later to maint). + (merge 974ce8078c mf/no-dashed-subcommands later to maint). + (merge f81935cc4d jc/perl-git-comment-typofix later to maint). + (merge 57ea241ef0 rs/t3700-clean-leftover later to maint). + (merge f1068efefe jk/drop-sha1-entry-pos later to maint). + (merge 0b006014c8 jk/hashcmp-memcmp later to maint). + (merge 1e22a9917b rj/add-chmod-error-message later to maint). + (merge 881529c846 rs/apply-lose-prefix-length later to maint). + (merge 6355a76802 rs/find-pack-entry-bisection later to maint). + (merge de3ce210ed rs/merge-microcleanup later to maint). + (merge 7f0a02be2f ah/doc-empty-string-is-false later to maint). + (merge 70ec6bd63b rs/t1002-do-not-use-sum later to maint). + (merge 2456990dfd sb/sha1-file-cleanup later to maint). + (merge 2aac933c62 hv/t5526-andand-chain-fix later to maint). + (merge c8d0c4fe9b sb/submodule-parallel-update later to maint). + (merge 794b7e1674 mg/format-ref-doc-fix later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index d5c9c4cab6..478b9431e0 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -216,15 +216,15 @@ boolean:: synonyms are accepted for 'true' and 'false'; these are all case-insensitive. - true;; Boolean true can be spelled as `yes`, `on`, `true`, - or `1`. Also, a variable defined without `= <value>` + true;; Boolean true literals are `yes`, `on`, `true`, + and `1`. Also, a variable defined without `= <value>` is taken as true. - false;; Boolean false can be spelled as `no`, `off`, - `false`, or `0`. + false;; Boolean false literals are `no`, `off`, `false`, + `0` and the empty string. + When converting value to the canonical form using `--bool` type -specifier; 'git config' will ensure that the output is "true" or +specifier, 'git config' will ensure that the output is "true" or "false" (spelled in lowercase). integer:: diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index cbce8ec638..5ca942ab5e 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -200,7 +200,10 @@ diff.algorithm:: + diff.wsErrorHighlight:: - A comma separated list of `old`, `new`, `context`, that - specifies how whitespace errors on lines are highlighted - with `color.diff.whitespace`. Can be overridden by the - command line option `--ws-error-highlight=<kind>` + Highlight whitespace errors in the `context`, `old` or `new` + lines of the diff. Multiple values are separated by comma, + `none` resets previous values, `default` reset the list to + `new` and `all` is a shorthand for `old,new,context`. The + whitespace errors are colored with `color.diff.whitespace`. + The command line option `--ws-error-highlight=<kind>` + overrides this setting. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 43d18a4c5c..56dedafcd4 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -300,15 +300,14 @@ ifndef::git-format-patch[] with --exit-code. --ws-error-highlight=<kind>:: - Highlight whitespace errors on lines specified by <kind> - in the color specified by `color.diff.whitespace`. <kind> - is a comma separated list of `old`, `new`, `context`. When - this option is not given, only whitespace errors in `new` - lines are highlighted. E.g. `--ws-error-highlight=new,old` - highlights whitespace errors on both deleted and added lines. - `all` can be used as a short-hand for `old,new,context`. - The `diff.wsErrorHighlight` configuration variable can be - used to specify the default behaviour. + Highlight whitespace errors in the `context`, `old` or `new` + lines of the diff. Multiple values are separated by comma, + `none` resets previous values, `default` reset the list to + `new` and `all` is a shorthand for `old,new,context`. When + this option is not given, and the configuration variable + `diff.wsErrorHighlight` is not set, only whitespace errors in + `new` lines are highlighted. The whitespace errors are colored + whith `color.diff.whitespace`. endif::git-format-patch[] diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 81bd0a7b77..d0b3358771 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -267,8 +267,8 @@ start-point is either a local or remote-tracking branch. 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 + A string that interpolates `%(fieldname)` from a branch ref being shown + and the object it points at. The format is the same as that of linkgit:git-for-each-ref[1]. Examples diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 03e187a105..bb370c9c7b 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -38,11 +38,12 @@ OPTIONS key. <format>:: - A string that interpolates `%(fieldname)` from the - object pointed at by a ref being shown. If `fieldname` + A string that interpolates `%(fieldname)` from a ref being shown + and the object it points at. If `fieldname` is prefixed with an asterisk (`*`) and the ref points - at a tag object, the value for the field in the object - tag refers is used. When unspecified, defaults to + at a tag object, use the value for the field in the object + which the tag object refers to (instead of the field in the tag object). + When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype) TAB %(refname)`. It also interpolates `%%` to `%`, and `%xx` where `xx` are hex digits interpolates to character with hex code @@ -156,8 +157,10 @@ HEAD:: otherwise. color:: - Change output color. Followed by `:<colorname>`, where names - are described in `color.branch.*`. + Change output color. Followed by `:<colorname>`, where color + names are described under Values in the "CONFIGURATION FILE" + section of linkgit:git-config[1]. For example, + `%(color:bold red)`. align:: Left-, middle-, or right-align the content between diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index c890328b02..6cbe462a77 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -23,6 +23,7 @@ SYNOPSIS [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] [--[no-]cover-letter] [--quiet] [--notes[=<ref>]] + [--progress] [<common diff options>] [ <since> | <revision range> ] @@ -283,6 +284,9 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. range are always formatted as creation patches, independently of this flag. +--progress:: + Show progress reports on stderr as patches are generated. + CONFIGURATION ------------- You can specify extra mail header lines to be added to each message, diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 5033483db4..720c7850e2 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -95,13 +95,6 @@ OPTIONS <tree> option the prefix of all submodule output will be the name of the parent project's <tree> object. ---parent-basename <basename>:: - For internal use only. In order to produce uniform output with the - --recurse-submodules option, this option can be used to provide the - basename of a parent's <tree> object to a submodule so the submodule - can prefix its output with the parent's name rather than the SHA1 of - the submodule. - -a:: --text:: Process binary files as if they were text. diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 04fdd8cf08..6b308ab6d0 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -64,6 +64,14 @@ OPTIONS ------- include::merge-options.txt[] +--signoff:: + Add Signed-off-by line by the committer at the end of the commit + log message. The meaning of a signoff depends on the project, + but it typically certifies that committer has + the rights to submit this work under the same license and + agrees to a Developer Certificate of Origin + (see http://developercertificate.org/ for more information). + -S[<keyid>]:: --gpg-sign[=<keyid>]:: GPG-sign the resulting merge commit. The `keyid` argument is diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 0a639664fd..3e76e99f38 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git push' [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] [--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-v | --verbose] [-u | --set-upstream] [--push-option=<string>] - [--[no-]signed|--sign=(true|false|if-asked)] + [--[no-]signed|--signed=(true|false|if-asked)] [--force-with-lease[=<refname>[:<expect>]]] [--no-verify] [<repository> [<refspec>...]] @@ -141,7 +141,7 @@ already exists on the remote side. information, see `push.followTags` in linkgit:git-config[1]. --[no-]signed:: ---sign=(true|false|if-asked):: +--signed=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be logged. If `false` or `--no-signed`, no signing will be diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 966abb0df8..f51c64939b 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [--atomic] - [--[no-]signed|--sign=(true|false|if-asked)] + [--[no-]signed|--signed=(true|false|if-asked)] [<host>:]<directory> [<ref>...] DESCRIPTION @@ -71,7 +71,7 @@ be in a separate packet, and the list must end with a flush packet. refs. --[no-]signed:: ---sign=(true|false|if-asked):: +--signed=(true|false|if-asked):: GPG-sign the push request to update refs on the receiving side, to allow it to be checked by the hooks and/or be logged. If `false` or `--no-signed`, no signing will be diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 1eb15afa1c..543fb425ee 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -188,8 +188,8 @@ This option is only applicable when listing tags without annotation lines. Defaults to HEAD. <format>:: - A string that interpolates `%(fieldname)` from the object - pointed at by a ref being shown. The format is the same as + A string that interpolates `%(fieldname)` from a tag ref being shown + and the object it points at. The format is the same as that of linkgit:git-for-each-ref[1]. When unspecified, defaults to `%(refname:strip=2)`. @@ -205,6 +205,9 @@ it in the repository configuration as follows: signingKey = <gpg-keyid> ------------------------------------- +`pager.tag` is only respected when listing tags, i.e., when `-l` is +used or implied. The default is to use a pager. +See linkgit:git-config[1]. DISCUSSION ---------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 7dd5e03280..6e3a6767e5 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -75,7 +75,8 @@ example the following invocations are equivalent: Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets `foo.bar` to the boolean true value (just like `[foo]bar` would in a config file). Including the equals but with an empty value (like `git -c -foo.bar= ...`) sets `foo.bar` to the empty string. +foo.bar= ...`) sets `foo.bar` to the empty string which ` git config +--bool` will convert to `false`. --exec-path[=<path>]:: Path to wherever your core Git programs are installed. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 2a2d7e2a4d..c4f2be2542 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -425,8 +425,8 @@ packet: git< capability=clean packet: git< capability=smudge packet: git< 0000 ------------------------ -Supported filter capabilities in version 2 are "clean" and -"smudge". +Supported filter capabilities in version 2 are "clean", "smudge", +and "delay". Afterwards Git sends a list of "key=value" pairs terminated with a flush packet. The list will contain at least the filter command @@ -512,12 +512,73 @@ the protocol then Git will stop the filter process and restart it with the next file that needs to be processed. Depending on the `filter.<driver>.required` flag Git will interpret that as error. -After the filter has processed a blob it is expected to wait for -the next "key=value" list containing a command. Git will close +After the filter has processed a command it is expected to wait for +a "key=value" list containing the next command. Git will close the command pipe on exit. The filter is expected to detect EOF and exit gracefully on its own. Git will wait until the filter process has stopped. +Delay +^^^^^ + +If the filter supports the "delay" capability, then Git can send the +flag "can-delay" after the filter command and pathname. This flag +denotes that the filter can delay filtering the current blob (e.g. to +compensate network latencies) by responding with no content but with +the status "delayed" and a flush packet. +------------------------ +packet: git> command=smudge +packet: git> pathname=path/testfile.dat +packet: git> can-delay=1 +packet: git> 0000 +packet: git> CONTENT +packet: git> 0000 +packet: git< status=delayed +packet: git< 0000 +------------------------ + +If the filter supports the "delay" capability then it must support the +"list_available_blobs" command. If Git sends this command, then the +filter is expected to return a list of pathnames representing blobs +that have been delayed earlier and are now available. +The list must be terminated with a flush packet followed +by a "success" status that is also terminated with a flush packet. If +no blobs for the delayed paths are available, yet, then the filter is +expected to block the response until at least one blob becomes +available. The filter can tell Git that it has no more delayed blobs +by sending an empty list. As soon as the filter responds with an empty +list, Git stops asking. All blobs that Git has not received at this +point are considered missing and will result in an error. + +------------------------ +packet: git> command=list_available_blobs +packet: git> 0000 +packet: git< pathname=path/testfile.dat +packet: git< pathname=path/otherfile.dat +packet: git< 0000 +packet: git< status=success +packet: git< 0000 +------------------------ + +After Git received the pathnames, it will request the corresponding +blobs again. These requests contain a pathname and an empty content +section. The filter is expected to respond with the smudged content +in the usual way as explained above. +------------------------ +packet: git> command=smudge +packet: git> pathname=path/testfile.dat +packet: git> 0000 +packet: git> 0000 # empty content! +packet: git< status=success +packet: git< 0000 +packet: git< SMUDGED_CONTENT +packet: git< 0000 +packet: git< 0000 # empty list, keep "status=success" unchanged! +------------------------ + +Example +^^^^^^^ + A long running filter demo implementation can be found in `contrib/long-running-filter/example.pl` located in the Git core repository. If you develop your own long running filter diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index b2514f4d44..623ed1a138 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -121,8 +121,8 @@ it is not suppressed by the `--no-verify` option. A non-zero exit means a failure of the hook and aborts the commit. It should not be used as replacement for pre-commit hook. -The sample `prepare-commit-msg` hook that comes with Git comments -out the `Conflicts:` part of a merge's commit message. +The sample `prepare-commit-msg` hook that comes with Git removes the +help message found in the commented portion of the commit template. commit-msg ~~~~~~~~~~ diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 4d6dac5770..973d19606b 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -173,13 +173,17 @@ endif::git-rev-list[] - '%Cblue': switch color to blue - '%Creset': reset color - '%C(...)': color specification, as described under Values in the - "CONFIGURATION FILE" section of linkgit:git-config[1]; - adding `auto,` at the beginning (e.g. `%C(auto,red)`) will emit - color only when colors are enabled for log output (by `color.diff`, - `color.ui`, or `--color`, and respecting the `auto` settings of the - former if we are going to a terminal). `auto` alone (i.e. - `%C(auto)`) will turn on auto coloring on the next placeholders - until the color is switched again. + "CONFIGURATION FILE" section of linkgit:git-config[1]. + By default, colors are shown only when enabled for log output (by + `color.diff`, `color.ui`, or `--color`, and respecting the `auto` + settings of the former if we are going to a terminal). `%C(auto,...)` + is accepted as a historical synonym for the default (e.g., + `%C(auto,red)`). Specifying `%C(always,...) will show the colors + even when color is not otherwise enabled (though consider + just using `--color=always` to enable color for the whole output, + including this format and anything else git might color). `auto` + alone (i.e. `%C(auto)`) will turn on auto coloring on the next + placeholders until the color is switched again. - '%m': left (`<`), right (`>`) or boundary (`-`) mark - '%n': newline - '%%': a raw '%' diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt deleted file mode 100644 index 22a39b9299..0000000000 --- a/Documentation/technical/api-builtin.txt +++ /dev/null @@ -1,73 +0,0 @@ -builtin API -=========== - -Adding a new built-in ---------------------- - -There are 4 things to do to add a built-in command implementation to -Git: - -. Define the implementation of the built-in command `foo` with - signature: - - int cmd_foo(int argc, const char **argv, const char *prefix); - -. Add the external declaration for the function to `builtin.h`. - -. Add the command to the `commands[]` table defined in `git.c`. - The entry should look like: - - { "foo", cmd_foo, <options> }, -+ -where options is the bitwise-or of: - -`RUN_SETUP`:: - If there is not a Git directory to work on, abort. If there - is a work tree, chdir to the top of it if the command was - invoked in a subdirectory. If there is no work tree, no - chdir() is done. - -`RUN_SETUP_GENTLY`:: - If there is a Git directory, chdir as per RUN_SETUP, otherwise, - don't chdir anywhere. - -`USE_PAGER`:: - - If the standard output is connected to a tty, spawn a pager and - feed our output to it. - -`NEED_WORK_TREE`:: - - Make sure there is a work tree, i.e. the command cannot act - on bare repositories. - This only makes sense when `RUN_SETUP` is also set. - -. Add `builtin/foo.o` to `BUILTIN_OBJS` in `Makefile`. - -Additionally, if `foo` is a new command, there are 3 more things to do: - -. Add tests to `t/` directory. - -. Write documentation in `Documentation/git-foo.txt`. - -. Add an entry for `git-foo` to `command-list.txt`. - -. Add an entry for `/git-foo` to `.gitignore`. - - -How a built-in is called ------------------------- - -The implementation `cmd_foo()` takes three parameters, `argc`, `argv, -and `prefix`. The first two are similar to what `main()` of a -standalone command would be called with. - -When `RUN_SETUP` is specified in the `commands[]` table, and when you -were started from a subdirectory of the work tree, `cmd_foo()` is called -after chdir(2) to the top of the work tree, and `prefix` gets the path -to the subdirectory the command started from. This allows you to -convert a user-supplied pathname (typically relative to that directory) -to a pathname relative to the top of the work tree. - -The return value from `cmd_foo()` becomes the exit status of the -command. diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt index 20741f345e..7a83a3a6e2 100644 --- a/Documentation/technical/api-config.txt +++ b/Documentation/technical/api-config.txt @@ -187,6 +187,10 @@ Same as `git_config_bool`, except that integers are returned as-is, and an `is_bool` flag is unset. `git_config_maybe_bool`:: +Deprecated. Use `git_parse_maybe_bool` instead. They are exactly the +same, except this function takes an unused argument `name`. + +`git_parse_maybe_bool`:: Same as `git_config_bool`, except that it returns -1 on error rather than dying. diff --git a/Documentation/technical/api-sub-process.txt b/Documentation/technical/api-sub-process.txt deleted file mode 100644 index 793508cf3e..0000000000 --- a/Documentation/technical/api-sub-process.txt +++ /dev/null @@ -1,59 +0,0 @@ -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/api-tree-walking.txt b/Documentation/technical/api-tree-walking.txt index 14af37c3f1..bde18622a8 100644 --- a/Documentation/technical/api-tree-walking.txt +++ b/Documentation/technical/api-tree-walking.txt @@ -55,9 +55,9 @@ Initializing `fill_tree_descriptor`:: - Initialize a `tree_desc` and decode its first entry given the sha1 of - a tree. Returns the `buffer` member if the sha1 is a valid tree - identifier and NULL otherwise. + Initialize a `tree_desc` and decode its first entry given the + object ID of a tree. Returns the `buffer` member if the latter + is a valid tree identifier and NULL otherwise. `setup_traverse_info`:: |