diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/2.15.2.txt | 47 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.16.0.txt | 58 | ||||
| -rw-r--r-- | Documentation/config.txt | 58 | ||||
| -rw-r--r-- | Documentation/git-branch.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-checkout.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-config.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-log.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-notes.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-prune.txt | 9 | ||||
| -rw-r--r-- | Documentation/git-reflog.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-send-email.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-stash.txt | 4 | ||||
| -rw-r--r-- | Documentation/git.txt | 15 | ||||
| -rw-r--r-- | Documentation/githooks.txt | 20 | ||||
| -rw-r--r-- | Documentation/gitrepository-layout.txt | 4 | ||||
| -rw-r--r-- | Documentation/technical/http-protocol.txt | 8 | ||||
| -rw-r--r-- | Documentation/technical/pack-protocol.txt | 43 |
17 files changed, 244 insertions, 60 deletions
diff --git a/Documentation/RelNotes/2.15.2.txt b/Documentation/RelNotes/2.15.2.txt new file mode 100644 index 0000000000..9f7e28f8a2 --- /dev/null +++ b/Documentation/RelNotes/2.15.2.txt @@ -0,0 +1,47 @@ +Git v2.15.2 Release Notes +========================= + +Fixes since v2.15.1 +------------------- + + * Recent update to the refs infrastructure implementation started + rewriting packed-refs file more often than before; this has been + optimized again for most trivial cases. + + * The SubmittingPatches document has been converted to produce an + HTML version via AsciiDoc/Asciidoctor. + + * Contrary to the documentation, "git pull -4/-6 other-args" did not + ask the underlying "git fetch" to go over IPv4/IPv6, which has been + corrected. + + * When "git rebase" prepared an mailbox of changes and fed it to "git + am" to replay them, it was confused when a stray "From " happened + to be in the log message of one of the replayed changes. This has + been corrected. + + * Command line completion (in contrib/) has been taught about the + "--copy" option of "git branch". + + * "git apply --inaccurate-eof" when used with "--ignore-space-change" + triggered an internal sanity check, which has been fixed. + + * The sequencer machinery (used by "git cherry-pick A..B", and "git + rebase -i", among other things) would have lost a commit if stopped + due to an unlockable index file, which has been fixed. + + * The three-way merge performed by "git cherry-pick" was confused + when a new submodule was added in the meantime, which has been + fixed (or "papered over"). + + * "git notes" sent its error message to its standard output stream, + which was corrected. + + * A few scripts (both in production and tests) incorrectly redirected + their error output. These have been corrected. + + * Clarify and enhance documentation for "merge-base --fork-point", as + it was clear what it computed but not why/what for. + + +Also contains various documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.16.0.txt b/Documentation/RelNotes/2.16.0.txt index c617e37dd8..431bd5e34a 100644 --- a/Documentation/RelNotes/2.16.0.txt +++ b/Documentation/RelNotes/2.16.0.txt @@ -61,7 +61,6 @@ UI, Workflows & Features * The SubmittingPatches document has been converted to produce an HTML version via AsciiDoc/Asciidoctor. - (merge 049e64aa50 bc/submitting-patches-in-asciidoc later to maint). * We learned to talk to watchman to speed up "git status" and other operations that need to see which paths have been modified. @@ -90,6 +89,13 @@ UI, Workflows & Features pattern" (aka "diff.*.xfuncname") to include a comment block, if exists, that immediately precedes it. + * "git config --expiry-date gc.reflogexpire" can read "2.weeks" from + the configuration and report it as a timestamp, just like "--int" + would read "1k" and report 1024, to help consumption by scripts. + + * The shell completion (in contrib/) learned that "git pull" can take + the "--autostash" option. + Performance, Internal Implementation, Development Support etc. @@ -130,6 +136,13 @@ Performance, Internal Implementation, Development Support etc. * Drop (perhaps overly cautious) sanity check before using the index read from the filesystem at runtime. + * The build procedure has been taught to avoid some unnecessary + instability in the build products. + + * A new mechanism to upgrade the wire protocol in place is proposed + and demonstrated that it works with the older versions of Git + without harming them. + Also contains various documentation updates and code clean-ups. @@ -206,7 +219,6 @@ Fixes since v2.15 * Recent update to the refs infrastructure implementation started rewriting packed-refs file more often than before; this has been optimized again for most trivial cases. - (merge 7c6bd25c7d mh/avoid-rewriting-packed-refs later to maint). * Some error messages did not quote filenames shown in it, which have been fixed. @@ -226,39 +238,31 @@ Fixes since v2.15 * Clarify and enhance documentation for "merge-base --fork-point", as it was clear what it computed but not why/what for. - (merge 6d1700b8af jc/merge-base-fork-point-doc later to maint). * A few scripts (both in production and tests) incorrectly redirected their error output. These have been corrected. - (merge eadf1c8f45 tz/redirect-fix later to maint). * "git notes" sent its error message to its standard output stream, which was corrected. - (merge 89b9e31dd5 tz/notes-error-to-stderr later to maint). * The three-way merge performed by "git cherry-pick" was confused when a new submodule was added in the meantime, which has been fixed (or "papered over"). - (merge c641ca6707 sb/test-cherry-pick-submodule-getting-in-a-way later to maint). * The sequencer machinery (used by "git cherry-pick A..B", and "git rebase -i", among other things) would have lost a commit if stopped due to an unlockable index file, which has been fixed. - (merge bd58886775 pw/sequencer-recover-from-unlockable-index later to maint). * "git apply --inaccurate-eof" when used with "--ignore-space-change" triggered an internal sanity check, which has been fixed. - (merge 4855de1233 rs/apply-inaccurate-eof-with-incomplete-line later to maint). * Command line completion (in contrib/) has been taught about the "--copy" option of "git branch". - (merge 41ca0f773e tz/complete-branch-copy later to maint). * When "git rebase" prepared an mailbox of changes and fed it to "git am" to replay them, it was confused when a stray "From " happened to be in the log message of one of the replayed changes. This has been corrected. - (merge ae3b2b04bb ew/rebase-mboxrd later to maint). * There was a recent semantic mismerge in the codepath to write out a section of a configuration section, which has been corrected. @@ -266,12 +270,40 @@ Fixes since v2.15 * Mentions of "git-rebase" and "git-am" (dashed form) still remained in end-user visible strings emitted by the "git rebase" command; they have been corrected. - (merge 82cb775c06 ks/rebase-no-git-foo later to maint). * Contrary to the documentation, "git pull -4/-6 other-args" did not ask the underlying "git fetch" to go over IPv4/IPv6, which has been corrected. - (merge ffb4568afe sw/pull-ipv46-passthru later to maint). + + * "git checkout --recursive" may overwrite and rewind the history of + the branch that happens to be checked out in submodule + repositories, which might not be desirable. Detach the HEAD but + still allow the recursive checkout to succeed in such a case. + (merge 57f22bf997 sb/submodule-recursive-checkout-detach-head later to maint). + + * "git branch --set-upstream" has been deprecated and (sort of) + removed, as "--set-upstream-to" is the preferred one these days. + The documentation still had "--set-upstream" listed on its + synopsys section, which has been corrected. + (merge a060f3d3d8 tz/branch-doc-remove-set-upstream later to maint). + + * Internaly we use 0{40} as a placeholder object name to signal the + codepath that there is no such object (e.g. the fast-forward check + while "git fetch" stores a new remote-tracking ref says "we know + there is no 'old' thing pointed at by the ref, as we are creating + it anew" by passing 0{40} for the 'old' side), and expect that a + codepath to locate an in-core object to return NULL as a sign that + the object does not exist. A look-up for an object that does not + exist however is quite costly with a repository with large number + of packfiles. This access pattern has been optimized. + (merge 87b5e236a1 jk/fewer-pack-rescan later to maint). + + * In addition to "git stash -m message", the command learned to + accept "git stash -mmessage" form. + (merge 5675473fcb ph/stash-save-m-option-fix later to maint). * Other minor doc, test and build updates and code cleanups. - (merge c5e3bc6ec4 sd/branch-copy later to maint). + (merge 1a1fc2d5b5 rd/man-prune-progress later to maint). + (merge 0ba014035a rd/man-reflog-add-n later to maint). + (merge e54b63359f rd/doc-notes-prune-fix later to maint). + (merge ff4c9b413a sp/doc-info-attributes later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index 531649cb40..c1598ee703 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -2108,15 +2108,40 @@ 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). + By default, Git determines the command line arguments to use + based on the basename of the configured SSH command (configured + using the environment variable `GIT_SSH` or `GIT_SSH_COMMAND` or + the config setting `core.sshCommand`). If the basename is + unrecognized, Git will attempt to detect support of OpenSSH + options by first invoking the configured SSH command with the + `-G` (print configuration) option and will subsequently use + OpenSSH options (if that is successful) or no options besides + the host and remote command (if it fails). ++ +The config variable `ssh.variant` can be set to override this detection. +Valid values are `ssh` (to use OpenSSH options), `plink`, `putty`, +`tortoiseplink`, `simple` (no options except the host and remote command). +The default auto-detection can be explicitly requested using the value +`auto`. Any other value is treated as `ssh`. This setting can also be +overridden via the environment variable `GIT_SSH_VARIANT`. ++ +The current command-line parameters used for each variant are as +follows: + -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`. +-- + +* `ssh` - [-p port] [-4] [-6] [-o option] [username@]host command + +* `simple` - [username@]host command + +* `plink` or `putty` - [-P port] [-4] [-6] [username@]host command + +* `tortoiseplink` - [-P port] [-4] [-6] -batch [username@]host command + +-- ++ +Except for the `simple` variant, command-line parameters are likely to +change as git gains new features. i18n.commitEncoding:: Character encoding the commit messages are stored in; Git itself @@ -2544,6 +2569,23 @@ The protocol names currently used by git are: `hg` to allow the `git-remote-hg` helper) -- +protocol.version:: + Experimental. If set, clients will attempt to communicate with a + server using the specified protocol version. If unset, no + attempt will be made by the client to communicate using a + particular protocol version, this results in protocol version 0 + being used. + Supported versions: ++ +-- + +* `0` - the original wire protocol. + +* `1` - the original wire protocol with the addition of a version string + in the initial response from the server. + +-- + pull.ff:: By default, Git does not create an extra merge commit when merging a commit that is a descendant of the current commit. Instead, the diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 520c53b5e8..b3084c99c1 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -14,7 +14,7 @@ SYNOPSIS [(--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' [--track | --no-track] [-l] [-f] <branchname> [<start-point>] 'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] 'git branch' --unset-upstream [<branchname>] 'git branch' (-m | -M) [<oldbranch>] <newbranch> @@ -86,7 +86,7 @@ OPTIONS --delete:: Delete a branch. The branch must be fully merged in its upstream branch, or in `HEAD` if no upstream was set with - `--track` or `--set-upstream`. + `--track` or `--set-upstream-to`. -D:: Shortcut for `--delete --force`. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index e108b0f74b..ca5fc9c798 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -264,6 +264,8 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. 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. + Just like linkgit:git-submodule[1], this will detach the + submodules HEAD. <branch>:: Branch to checkout; if it refers to a branch (i.e., a name that, @@ -272,11 +274,11 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode. commit, your HEAD becomes "detached" and you are no longer on any branch (see below for details). + -As a special case, the `"@{-N}"` syntax for the N-th last branch/commit -checks out branches (instead of detaching). You may also specify -`-` which is synonymous with `"@{-1}"`. +You can use the `"@{-N}"` syntax to refer to the N-th last +branch/commit checked out using "git checkout" operation. You may +also specify `-` which is synonymous to `"@{-1}`. + -As a further special case, you may use `"A...B"` as a shortcut for the +As a special case, you may use `"A...B"` as a shortcut for the merge base of `A` and `B` if there is exactly one merge base. You can leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 4edd09fc6b..14da5fc157 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -180,6 +180,11 @@ See also <<FILES>>. value (but you can use `git config section.variable ~/` from the command line to let your shell do the expansion). +--expiry-date:: + `git config` will ensure that the output is converted from + a fixed or relative date-string to a timestamp. This option + has no effect when setting the value. + -z:: --null:: For all options that output values and/or keys, always diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 32246fdb00..5437f8b0f0 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -38,6 +38,13 @@ OPTIONS are shown as if 'short' were given, otherwise no ref names are shown. The default option is 'short'. +--decorate-refs=<pattern>:: +--decorate-refs-exclude=<pattern>:: + If no `--decorate-refs` is given, pretend as if all refs were + included. For each candidate, do not use it for decoration if it + matches any patterns given to `--decorate-refs-exclude` or if it + doesn't match any of the patterns given to `--decorate-refs`. + --source:: Print out the ref name given on the command line by which each commit was reached. diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 43677297f3..e8dec1b3c8 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -18,7 +18,7 @@ SYNOPSIS 'git notes' merge --commit [-v | -q] 'git notes' merge --abort [-v | -q] 'git notes' remove [--ignore-missing] [--stdin] [<object>...] -'git notes' prune [-n | -v] +'git notes' prune [-n] [-v] 'git notes' get-ref diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 7a493c80f7..a37c0af931 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -9,7 +9,7 @@ git-prune - Prune all unreachable objects from the object database SYNOPSIS -------- [verse] -'git prune' [-n] [-v] [--expire <expire>] [--] [<head>...] +'git prune' [-n] [-v] [--progress] [--expire <time>] [--] [<head>...] DESCRIPTION ----------- @@ -42,12 +42,15 @@ OPTIONS --verbose:: Report all removed objects. -\--:: - Do not interpret any more arguments as options. +--progress:: + Show progress. --expire <time>:: Only expire loose objects older than <time>. +\--:: + Do not interpret any more arguments as options. + <head>...:: In addition to objects reachable from any of our references, keep objects diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 44c736f1a8..472a6808cd 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -20,9 +20,9 @@ depending on the subcommand: 'git reflog' ['show'] [log-options] [<ref>] 'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>] [--rewrite] [--updateref] [--stale-fix] - [--dry-run] [--verbose] [--all | <refs>...] + [--dry-run | -n] [--verbose] [--all | <refs>...] 'git reflog delete' [--rewrite] [--updateref] - [--dry-run] [--verbose] ref@\{specifier\}... + [--dry-run | -n] [--verbose] ref@\{specifier\}... 'git reflog exists' <ref> Reference logs, or "reflogs", record when the tips of branches and diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index bac9014ac7..8060ea35c5 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -203,9 +203,9 @@ a password is obtained using 'git-credential'. specify a full pathname of a sendmail-like program instead; the program must support the `-i` option. Default value can be specified by the `sendemail.smtpServer` configuration - option; the built-in default is `/usr/sbin/sendmail` or - `/usr/lib/sendmail` if such program is available, or - `localhost` otherwise. + option; the built-in default is to search for `sendmail` in + `/usr/sbin`, `/usr/lib` and $PATH if such program is + available, falling back to `localhost` otherwise. --smtp-server-port=<port>:: Specifies a port different from the default port (SMTP diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 8be661007d..056dfb8661 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -175,14 +175,14 @@ create:: return its object name, without storing it anywhere in the ref namespace. This is intended to be useful for scripts. It is probably not - the command you want to use; see "save" above. + the command you want to use; see "push" above. store:: Store a given stash created via 'git stash create' (which is a dangling merge commit) in the stash ref, updating the stash reflog. This is intended to be useful for scripts. It is - probably not the command you want to use; see "save" above. + probably not the command you want to use; see "push" above. DISCUSSION ---------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 483a1f3547..e75db104e3 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -522,11 +522,10 @@ other If either of these environment variables is set then 'git fetch' and 'git push' will use the specified command instead of 'ssh' when they need to connect to a remote system. - The command will be given exactly two or four arguments: the - 'username@host' (or just 'host') from the URL and the shell - command to execute on that remote system, optionally preceded by - `-p` (literally) and the 'port' from the URL when it specifies - something other than the default SSH port. + The command-line parameters passed to the configured command are + determined by the ssh variant. See `ssh.variant` option in + linkgit:git-config[1] for details. + + `$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted by the shell, which allows additional arguments to be included. @@ -705,6 +704,12 @@ of clones and fetches. which feed potentially-untrusted URLS to git commands. See linkgit:git-config[1] for more details. +`GIT_PROTOCOL`:: + For internal use only. Used in handshaking the wire protocol. + Contains a colon ':' separated list of keys with optional values + 'key[=value]'. Presence of unknown keys and values must be + ignored. + `GIT_OPTIONAL_LOCKS`:: If set to `0`, Git will complete any requested operation without performing any optional sub-operations that require taking a lock. diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 0bb0042d8c..b63f2ea860 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -223,8 +223,8 @@ to the user by writing to standard error. pre-receive ~~~~~~~~~~~ -This hook is invoked by 'git-receive-pack' on the remote repository, -which happens when a 'git push' is done on a local repository. +This hook is invoked by 'git-receive-pack' when it reacts to +'git push' and updates reference(s) in its repository. Just before starting to update refs on the remote repository, the pre-receive hook is invoked. Its exit status determines the success or failure of the update. @@ -264,8 +264,8 @@ linkgit:git-receive-pack[1] for some caveats. update ~~~~~~ -This hook is invoked by 'git-receive-pack' on the remote repository, -which happens when a 'git push' is done on a local repository. +This hook is invoked by 'git-receive-pack' when it reacts to +'git push' and updates reference(s) in its repository. Just before updating the ref on the remote repository, the update hook is invoked. Its exit status determines the success or failure of the ref update. @@ -309,8 +309,8 @@ unannotated tags to be pushed. post-receive ~~~~~~~~~~~~ -This hook is invoked by 'git-receive-pack' on the remote repository, -which happens when a 'git push' is done on a local repository. +This hook is invoked by 'git-receive-pack' when it reacts to +'git push' and updates reference(s) in its repository. It executes on the remote repository once after all the refs have been updated. @@ -348,8 +348,8 @@ will be set to zero, `GIT_PUSH_OPTION_COUNT=0`. post-update ~~~~~~~~~~~ -This hook is invoked by 'git-receive-pack' on the remote repository, -which happens when a 'git push' is done on a local repository. +This hook is invoked by 'git-receive-pack' when it reacts to +'git push' and updates reference(s) in its repository. It executes on the remote repository once after all the refs have been updated. @@ -379,8 +379,8 @@ for the user. push-to-checkout ~~~~~~~~~~~~~~~~ -This hook is invoked by 'git-receive-pack' on the remote repository, -which happens when a 'git push' is done on a local repository, when +This hook is invoked by 'git-receive-pack' when it reacts to +'git push' and updates reference(s) in its repository, and when the push tries to update the branch that is currently checked out and the `receive.denyCurrentBranch` configuration variable is set to `updateInstead`. Such a push by default is refused if the working diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index adf9554ad2..c60bcad44a 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -208,6 +208,10 @@ info/exclude:: 'git clean' look at it but the core Git commands do not look at it. See also: linkgit:gitignore[5]. +info/attributes:: + Defines which attributes to assign to a path, similar to per-directory + `.gitattributes` files. See also: linkgit:gitattributes[5]. + info/sparse-checkout:: This file stores sparse checkout patterns. See also: linkgit:git-read-tree[1]. diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt index 1c561bdd92..a0e45f2889 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/technical/http-protocol.txt @@ -219,6 +219,10 @@ smart server reply: S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n +The client may send Extra Parameters (see +Documentation/technical/pack-protocol.txt) as a colon-separated string +in the Git-Protocol HTTP header. + Dumb Server Response ^^^^^^^^^^^^^^^^^^^^ Dumb servers MUST respond with the dumb server reply format. @@ -269,7 +273,11 @@ the C locale ordering. The stream SHOULD include the default ref named `HEAD` as the first ref. The stream MUST include capability declarations behind a NUL on the first ref. +The returned response contains "version 1" if "version=1" was sent as an +Extra Parameter. + smart_reply = PKT-LINE("# service=$servicename" LF) + *1("version 1") ref_list "0000" ref_list = empty_list / non_empty_list diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index ed1eae8b83..cd31edc91e 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -39,6 +39,19 @@ communicates with that invoked process over the SSH connection. The file:// transport runs the 'upload-pack' or 'receive-pack' process locally and communicates with it over a pipe. +Extra Parameters +---------------- + +The protocol provides a mechanism in which clients can send additional +information in its first message to the server. These are called "Extra +Parameters", and are supported by the Git, SSH, and HTTP protocols. + +Each Extra Parameter takes the form of `<key>=<value>` or `<key>`. + +Servers that receive any such Extra Parameters MUST ignore all +unrecognized keys. Currently, the only Extra Parameter recognized is +"version=1". + Git Transport ------------- @@ -46,18 +59,25 @@ The Git transport starts off by sending the command and repository on the wire using the pkt-line format, followed by a NUL byte and a hostname parameter, terminated by a NUL byte. - 0032git-upload-pack /project.git\0host=myserver.com\0 + 0033git-upload-pack /project.git\0host=myserver.com\0 + +The transport may send Extra Parameters by adding an additional NUL +byte, and then adding one or more NUL-terminated strings: + + 003egit-upload-pack /project.git\0host=myserver.com\0\0version=1\0 -- - git-proto-request = request-command SP pathname NUL [ host-parameter NUL ] + git-proto-request = request-command SP pathname NUL + [ host-parameter NUL ] [ NUL extra-parameters ] request-command = "git-upload-pack" / "git-receive-pack" / "git-upload-archive" ; case sensitive pathname = *( %x01-ff ) ; exclude NUL host-parameter = "host=" hostname [ ":" port ] + extra-parameters = 1*extra-parameter + extra-parameter = 1*( %x01-ff ) NUL -- -Only host-parameter is allowed in the git-proto-request. Clients -MUST NOT attempt to send additional parameters. It is used for the +host-parameter is used for the git-daemon name based virtual hosting. See --interpolated-path option to git daemon, with the %H/%CH format characters. @@ -117,6 +137,12 @@ we execute it without the leading '/'. v ssh user@example.com "git-upload-pack '~alice/project.git'" +Depending on the value of the `protocol.version` configuration variable, +Git may attempt to send Extra Parameters as a colon-separated string in +the GIT_PROTOCOL environment variable. This is done only if +the `ssh.variant` configuration variable indicates that the ssh command +supports passing environment variables as an argument. + A few things to remember here: - The "command name" is spelled with dash (e.g. git-upload-pack), but @@ -137,11 +163,13 @@ Reference Discovery ------------------- When the client initially connects the server will immediately respond -with a listing of each reference it has (all branches and tags) along +with a version number (if "version=1" is sent as an Extra Parameter), +and a listing of each reference it has (all branches and tags) along with the object name that each reference currently points to. - $ echo -e -n "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" | + $ echo -e -n "0044git-upload-pack /schacon/gitbook.git\0host=example.com\0\0version=1\0" | nc -v example.com 9418 + 000aversion 1 00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress include-tag 00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration @@ -165,7 +193,8 @@ immediately after the ref itself, if presented. A conforming server MUST peel the ref if it's an annotated tag. ---- - advertised-refs = (no-refs / list-of-refs) + advertised-refs = *1("version 1") + (no-refs / list-of-refs) *shallow flush-pkt |