diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/Makefile | 10 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.9.txt | 46 | ||||
| -rw-r--r-- | Documentation/git-checkout.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-column.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-for-each-ref.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-http-backend.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-notes.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-p4.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-pull.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-remote-ext.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-remote-fd.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-show-ref.txt | 1 | ||||
| -rw-r--r-- | Documentation/gitattributes.txt | 9 | ||||
| -rw-r--r-- | Documentation/gitignore.txt | 2 | ||||
| -rw-r--r-- | Documentation/gitk.txt | 16 | ||||
| -rw-r--r-- | Documentation/merge-options.txt | 9 | ||||
| -rw-r--r-- | Documentation/revisions.txt | 2 | ||||
| -rw-r--r-- | Documentation/technical/http-protocol.txt | 225 |
18 files changed, 209 insertions, 167 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 36c58fc646..fc6b2cf9ec 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -2,6 +2,9 @@ MAN1_TXT = MAN5_TXT = MAN7_TXT = +TECH_DOCS = +ARTICLES = +SP_ARTICLES = MAN1_TXT += $(filter-out \ $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ @@ -37,12 +40,12 @@ MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT)) OBSOLETE_HTML = git-remote-helpers.html DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML) -ARTICLES = howto-index +ARTICLES += howto-index ARTICLES += everyday ARTICLES += git-tools ARTICLES += git-bisect-lk2009 # with their own formatting rules. -SP_ARTICLES = user-manual +SP_ARTICLES += user-manual SP_ARTICLES += howto/new-command SP_ARTICLES += howto/revert-branch-rebase SP_ARTICLES += howto/using-merge-subtree @@ -60,7 +63,8 @@ SP_ARTICLES += howto/maintain-git API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) -TECH_DOCS = technical/index-format +TECH_DOCS += technical/http-protocol +TECH_DOCS += technical/index-format TECH_DOCS += technical/pack-format TECH_DOCS += technical/pack-heuristics TECH_DOCS += technical/pack-protocol diff --git a/Documentation/RelNotes/1.9.txt b/Documentation/RelNotes/1.9.txt index 7bcf371c5f..43c7b682a6 100644 --- a/Documentation/RelNotes/1.9.txt +++ b/Documentation/RelNotes/1.9.txt @@ -87,6 +87,8 @@ Foreign interfaces, subsystems and ports. * The build procedure is aware of MirBSD now. + * Various "git p4", "git svn" and "gitk" updates. + UI, Workflows & Features @@ -215,6 +217,50 @@ Unless otherwise noted, all the fixes since v1.8.5 in the maintenance track are contained in this release (see the maintenance releases' notes for details). + * The pathspec matching code, while comparing two trees (e.g. "git + diff A B -- path1 path2") was too agrresive and failed to match + some paths when multiple pathspecs were involved. + (merge e4ddb05 as/tree-walk-fix-aggressive-short-cut later to maint). + + * "git repack --max-pack-size=8g" stopped being parsed correctly when + the command was reimplemented in C. + (merge b861e23 sb/repack-in-c later to maint). + + * An earlier update in v1.8.4.x to "git rev-list --objects" with + negative ref had performance regression. + (merge 200abe7 jk/mark-edges-uninteresting later to maint). + + * A recent update to "git send-email" broke platforms where + /etc/ssl/certs/ directory exists, but it cannot used as SSL_ca_path + (e.g. Fedora rawhide). + (merge 01645b7 rk/send-email-ssl-cert later to maint). + + * A handful of bugs around interpreting $branch@{upstream} notation + and its lookalike, when $branch part has interesting characters, + e.g. "@", and ":", have been fixed. + (merge 9892d5d jk/interpret-branch-name-fix later to maint). + + * "git clone" would fail to clone from a repository that has a ref + directly under "refs/", e.g. "refs/stash", because different + validation paths do different things on such a refname. Loosen the + client side's validation to allow such a ref. + (merge 4c22408 jk/allow-fetch-onelevel-refname later to maint). + + * "git log --left-right A...B" lost the "leftness" of commits + reachable from A when A is a tag as a side effect of a recent + bugfix. This is a regression in 1.8.4.x series. + (merge a743528 jc/revision-range-unpeel later to maint). + + * documentations to "git pull" hinted there is an "-m" option because + it incorrectly shared the documentation with "git merge". + (merge 08f19cf jc/maint-pull-docfix later to maint). + + * "git diff A B submod" and "git diff A B submod/" ought to have done + the same for a submodule "submod", but didn't. + + * "git clone $origin foo\bar\baz" on Windows failed to create the + leading directories (i.e. a moral-equivalent of "mkdir -p"). + * "submodule.*.update=checkout", when propagated from .gitmodules to .git/config, turned into a "submodule.*.update=none", which did not make much sense. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 91294f89c8..33ad2adf5c 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -232,8 +232,8 @@ 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 -checks out the branch (instead of detaching). You may also specify +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}"`. + As a further special case, you may use `"A...B"` as a shortcut for the diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt index 5d6f1cc464..03d18465d4 100644 --- a/Documentation/git-column.txt +++ b/Documentation/git-column.txt @@ -43,11 +43,6 @@ OPTIONS --padding=<N>:: The number of spaces between columns. One space by default. - -Author ------- -Written by Nguyen Thai Ngoc Duy <pclouds@gmail.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 94f5c465da..42408752d0 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -219,13 +219,9 @@ eval=`git for-each-ref --shell --format="$fmt" \ eval "$eval" ------------ -Author ------- -Written by Junio C Hamano <gitster@pobox.com>. - -Documentation -------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +SEE ALSO +-------- +linkgit:git-show-ref[1] GIT --- diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index e3bcdb50e3..e8c13f60ae 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -263,14 +263,6 @@ identifying information of the remote user who performed the push. All CGI environment variables are available to each of the hooks invoked by the 'git-receive-pack'. -Author ------- -Written by Shawn O. Pearce <spearce@spearce.org>. - -Documentation --------------- -Documentation by Shawn O. Pearce <spearce@spearce.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 46ef0466be..84bb0fecb0 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -375,16 +375,6 @@ does not match any refs is silently ignored. If not set in the environment, the list of notes to copy depends on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. - -Author ------- -Written by Johannes Schindelin <johannes.schindelin@gmx.de> and -Johan Herland <johan@herland.net> - -Documentation -------------- -Documentation by Johannes Schindelin and Johan Herland - GIT --- Part of the linkgit:git[7] suite diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 8cba16d67f..6ab5f9497a 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -168,7 +168,8 @@ All commands except clone accept these options. --git-dir <dir>:: Set the 'GIT_DIR' environment variable. See linkgit:git[1]. ---verbose, -v:: +-v:: +--verbose:: Provide more progress information. Sync options @@ -279,7 +280,8 @@ These options can be used to modify 'git p4 submit' behavior. Export tags from Git as p4 labels. Tags found in Git are applied to the perforce working directory. ---dry-run, -n:: +-n:: +--dry-run:: Show just what commits would be submitted to p4; do not change state in Git or p4. diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 6083aab87b..200eb22260 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -99,10 +99,10 @@ must be given before the options meant for 'git fetch'. Options related to merging ~~~~~~~~~~~~~~~~~~~~~~~~~~ -include::merge-options.txt[] - :git-pull: 1 +include::merge-options.txt[] + -r:: --rebase[=false|true|preserve]:: When true, rebase the current branch on top of the upstream diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt index 8cfc748ae2..cd0bb77e4a 100644 --- a/Documentation/git-remote-ext.txt +++ b/Documentation/git-remote-ext.txt @@ -116,11 +116,6 @@ begins with `ext::`. Examples: determined by the helper using environment variables (see above). -Documentation --------------- -Documentation by Ilari Liusvaara, Jonathan Nieder and the Git list -<git@vger.kernel.org> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt index 933c2adaf6..bcd37668e3 100644 --- a/Documentation/git-remote-fd.txt +++ b/Documentation/git-remote-fd.txt @@ -50,10 +50,6 @@ EXAMPLES `git push fd::7,8/bar master`:: Same as above. -Documentation --------------- -Documentation by Ilari Liusvaara and the Git list <git@vger.kernel.org> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index b0a309b117..ffd1b03a9c 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -175,6 +175,7 @@ FILES SEE ALSO -------- +linkgit:git-for-each-ref[1], linkgit:git-ls-remote[1], linkgit:git-update-ref[1], linkgit:gitrepository-layout[5] diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index b322a2666c..643c1ba929 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -930,9 +930,12 @@ state. DEFINING MACRO ATTRIBUTES ------------------------- -Custom macro attributes can be defined only in the `.gitattributes` -file at the toplevel (i.e. not in any subdirectory). The built-in -macro attribute "binary" is equivalent to: +Custom macro attributes can be defined only in top-level gitattributes +files (`$GIT_DIR/info/attributes`, the `.gitattributes` file at the +top level of the working tree, or the global or system-wide +gitattributes files), not in `.gitattributes` files in working tree +subdirectories. The built-in macro attribute "binary" is equivalent +to: ------------ [attr]binary -diff -merge -text diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 205e80ef88..b08d34d84e 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -7,7 +7,7 @@ gitignore - Specifies intentionally untracked files to ignore SYNOPSIS -------- -$GIT_DIR/info/exclude, .gitignore +$HOME/.config/git/ignore, $GIT_DIR/info/exclude, .gitignore DESCRIPTION ----------- diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index d44e14c138..1e9e38ae40 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -98,6 +98,22 @@ linkgit:git-rev-list[1] for a complete list. (See "History simplification" in linkgit:git-log[1] for a more detailed explanation.) +-L<start>,<end>:<file>:: +-L:<regex>:<file>:: + + Trace the evolution of the line range given by "<start>,<end>" + (or the funcname regex <regex>) within the <file>. You may + not give any pathspec limiters. This is currently limited to + a walk starting from a single revision, i.e., you may only + give zero or one positive revision arguments. + You can specify this option more than once. ++ +*Note:* gitk (unlike linkgit:git-log[1]) currently only understands +this option if you specify it "glued together" with its argument. Do +*not* put a space after `-L`. ++ +include::line-range-format.txt[] + <revision range>:: Limit the revisions to show. This can be either a single revision diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index afba8d4f3b..e1343155fa 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -14,9 +14,12 @@ inspect and further tweak the merge result before committing. further edit the auto-generated merge message, so that the user can explain and justify the merge. The `--no-edit` option can be used to accept the auto-generated message (this is generally - discouraged). The `--edit` (or `-e`) option is still useful if you are - giving a draft message with the `-m` option from the command line - and want to edit it in the editor. + discouraged). +ifndef::git-pull[] +The `--edit` (or `-e`) option is still useful if you are +giving a draft message with the `-m` option from the command line +and want to edit it in the editor. +endif::git-pull[] + Older scripts may depend on the historical behaviour of not allowing the user to edit the merge log message. They will see an editor opened when diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 2c06ed34ad..5a286d0d61 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -88,7 +88,7 @@ some output processing may assume ref names in UTF-8. branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'. '@\{-<n>\}', e.g. '@\{-1\}':: - The construct '@\{-<n>\}' means the <n>th branch checked out + The construct '@\{-<n>\}' means the <n>th branch/commit checked out before the current one. '<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt index d21d77d1de..544373b16f 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/technical/http-protocol.txt @@ -20,13 +20,13 @@ URL syntax documented by RFC 1738, so they are of the form: http://<host>:<port>/<path>?<searchpart> -Within this documentation the placeholder $GIT_URL will stand for +Within this documentation the placeholder `$GIT_URL` will stand for the http:// repository URL entered by the end-user. -Servers SHOULD handle all requests to locations matching $GIT_URL, as +Servers SHOULD handle all requests to locations matching `$GIT_URL`, as both the "smart" and "dumb" HTTP protocols used by Git operate by appending additional path components onto the end of the user -supplied $GIT_URL string. +supplied `$GIT_URL` string. An example of a dumb client requesting for a loose object: @@ -43,10 +43,10 @@ An example of a request to a submodule: $GIT_URL: http://example.com/git/repo.git/path/submodule.git URL request: http://example.com/git/repo.git/path/submodule.git/info/refs -Clients MUST strip a trailing '/', if present, from the user supplied -$GIT_URL string to prevent empty path tokens ('//') from appearing +Clients MUST strip a trailing `/`, if present, from the user supplied +`$GIT_URL` string to prevent empty path tokens (`//`) from appearing in any URL sent to a server. Compatible clients MUST expand -'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'. +`$GIT_URL/info/refs` as `foo/info/refs` and not `foo//info/refs`. Authentication @@ -103,14 +103,14 @@ Except where noted, all standard HTTP behavior SHOULD be assumed by both client and server. This includes (but is not necessarily limited to): -If there is no repository at $GIT_URL, or the resource pointed to by a -location matching $GIT_URL does not exist, the server MUST NOT respond -with '200 OK' response. A server SHOULD respond with -'404 Not Found', '410 Gone', or any other suitable HTTP status code +If there is no repository at `$GIT_URL`, or the resource pointed to by a +location matching `$GIT_URL` does not exist, the server MUST NOT respond +with `200 OK` response. A server SHOULD respond with +`404 Not Found`, `410 Gone`, or any other suitable HTTP status code which does not imply the resource exists as requested. -If there is a repository at $GIT_URL, but access is not currently -permitted, the server MUST respond with the '403 Forbidden' HTTP +If there is a repository at `$GIT_URL`, but access is not currently +permitted, the server MUST respond with the `403 Forbidden` HTTP status code. Servers SHOULD support both HTTP 1.0 and HTTP 1.1. @@ -126,9 +126,9 @@ Servers MAY return ETag and/or Last-Modified headers. Clients MAY revalidate cached entities by including If-Modified-Since and/or If-None-Match request headers. -Servers MAY return '304 Not Modified' if the relevant headers appear +Servers MAY return `304 Not Modified` if the relevant headers appear in the request and the entity has not changed. Clients MUST treat -'304 Not Modified' identical to '200 OK' by reusing the cached entity. +`304 Not Modified` identical to `200 OK` by reusing the cached entity. Clients MAY reuse a cached entity without revalidation if the Cache-Control and/or Expires header permits caching. Clients and @@ -148,7 +148,7 @@ HTTP clients that only support the "dumb" protocol MUST discover references by making a request for the special info/refs file of the repository. -Dumb HTTP clients MUST make a GET request to $GIT_URL/info/refs, +Dumb HTTP clients MUST make a `GET` request to `$GIT_URL/info/refs`, without any search/query parameters. C: GET $GIT_URL/info/refs HTTP/1.0 @@ -161,21 +161,21 @@ without any search/query parameters. S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{} The Content-Type of the returned info/refs entity SHOULD be -"text/plain; charset=utf-8", but MAY be any content type. +`text/plain; charset=utf-8`, but MAY be any content type. Clients MUST NOT attempt to validate the returned Content-Type. Dumb servers MUST NOT return a return type starting with -"application/x-git-". +`application/x-git-`. Cache-Control headers MAY be returned to disable caching of the returned entity. When examining the response clients SHOULD only examine the HTTP -status code. Valid responses are '200 OK', or '304 Not Modified'. +status code. Valid responses are `200 OK`, or `304 Not Modified`. The returned content is a UNIX formatted text file describing each ref and its known value. The file SHOULD be sorted by name according to the C locale ordering. The file SHOULD NOT include -the default ref named 'HEAD'. +the default ref named `HEAD`. info_refs = *( ref_record ) ref_record = any_ref / peeled_ref @@ -192,13 +192,14 @@ HTTP clients that support the "smart" protocol (or both the a parameterized request for the info/refs file of the repository. The request MUST contain exactly one query parameter, -'service=$servicename', where $servicename MUST be the service +`service=$servicename`, where `$servicename` MUST be the service name the client wishes to contact to complete the operation. The request MUST NOT contain additional query parameters. C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0 - dumb server reply: +dumb server reply: + S: 200 OK S: S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint @@ -206,7 +207,8 @@ The request MUST NOT contain additional query parameters. S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0 S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{} - smart server reply: +smart server reply: + S: 200 OK S: Content-Type: application/x-git-upload-pack-advertisement S: Cache-Control: no-cache @@ -228,7 +230,7 @@ Smart Server Response ^^^^^^^^^^^^^^^^^^^^^ If the server does not recognize the requested service name, or the requested service name has been disabled by the server administrator, -the server MUST respond with the '403 Forbidden' HTTP status code. +the server MUST respond with the `403 Forbidden` HTTP status code. Otherwise, smart servers MUST respond with the smart server reply format for the requested service name. @@ -236,35 +238,35 @@ format for the requested service name. Cache-Control headers SHOULD be used to disable caching of the returned entity. -The Content-Type MUST be 'application/x-$servicename-advertisement'. +The Content-Type MUST be `application/x-$servicename-advertisement`. Clients SHOULD fall back to the dumb protocol if another content type is returned. When falling back to the dumb protocol clients -SHOULD NOT make an additional request to $GIT_URL/info/refs, but +SHOULD NOT make an additional request to `$GIT_URL/info/refs`, but instead SHOULD use the response already in hand. Clients MUST NOT continue if they do not support the dumb protocol. -Clients MUST validate the status code is either '200 OK' or -'304 Not Modified'. +Clients MUST validate the status code is either `200 OK` or +`304 Not Modified`. Clients MUST validate the first five bytes of the response entity -matches the regex "^[0-9a-f]{4}#". If this test fails, clients +matches the regex `^[0-9a-f]{4}#`. If this test fails, clients MUST NOT continue. Clients MUST parse the entire response as a sequence of pkt-line records. -Clients MUST verify the first pkt-line is "# service=$servicename". +Clients MUST verify the first pkt-line is `# service=$servicename`. Servers MUST set $servicename to be the request parameter value. Servers SHOULD include an LF at the end of this line. Clients MUST ignore an LF at the end of the line. -Servers MUST terminate the response with the magic "0000" end +Servers MUST terminate the response with the magic `0000` end pkt-line marker. The returned response is a pkt-line stream describing each ref and its known value. The stream SHOULD be sorted by name according to the C locale ordering. The stream SHOULD include the default ref -named 'HEAD' as the first ref. The stream MUST include capability +named `HEAD` as the first ref. The stream MUST include capability declarations behind a NUL on the first ref. smart_reply = PKT-LINE("# service=$servicename" LF) @@ -286,12 +288,13 @@ declarations behind a NUL on the first ref. peeled_ref = PKT-LINE(obj-id SP name LF) PKT-LINE(obj-id SP name "^{}" LF + Smart Service git-upload-pack ------------------------------ -This service reads from the repository pointed to by $GIT_URL. +This service reads from the repository pointed to by `$GIT_URL`. Clients MUST first perform ref discovery with -'$GIT_URL/info/refs?service=git-upload-pack'. +`$GIT_URL/info/refs?service=git-upload-pack`. C: POST $GIT_URL/git-upload-pack HTTP/1.0 C: Content-Type: application/x-git-upload-pack-request @@ -313,10 +316,10 @@ to prevent caching of the response. Servers SHOULD support all capabilities defined here. -Clients MUST send at least one 'want' command in the request body. -Clients MUST NOT reference an id in a 'want' command which did not +Clients MUST send at least one "want" command in the request body. +Clients MUST NOT reference an id in a "want" command which did not appear in the response obtained through ref discovery unless the -server advertises capability "allow-tip-sha1-in-want". +server advertises capability `allow-tip-sha1-in-want`. compute_request = want_list have_list @@ -332,128 +335,128 @@ server advertises capability "allow-tip-sha1-in-want". have_list = *PKT-LINE("have" SP id LF) TODO: Document this further. -TODO: Don't use uppercase for variable names below. The Negotiation Algorithm ~~~~~~~~~~~~~~~~~~~~~~~~~ The computation to select the minimal pack proceeds as follows -(c = client, s = server): +(C = client, S = server): + +'init step:' + +C: Use ref discovery to obtain the advertised refs. + +C: Place any object seen into set `advertised`. - init step: - (c) Use ref discovery to obtain the advertised refs. - (c) Place any object seen into set ADVERTISED. +C: Build an empty set, `common`, to hold the objects that are later + determined to be on both ends. - (c) Build an empty set, COMMON, to hold the objects that are later - determined to be on both ends. - (c) Build a set, WANT, of the objects from ADVERTISED the client - wants to fetch, based on what it saw during ref discovery. +C: Build a set, `want`, of the objects from `advertised` the client + wants to fetch, based on what it saw during ref discovery. - (c) Start a queue, C_PENDING, ordered by commit time (popping newest - first). Add all client refs. When a commit is popped from - the queue its parents SHOULD be automatically inserted back. - Commits MUST only enter the queue once. +C: Start a queue, `c_pending`, ordered by commit time (popping newest + first). Add all client refs. When a commit is popped from + the queue its parents SHOULD be automatically inserted back. + Commits MUST only enter the queue once. - one compute step: - (c) Send one $GIT_URL/git-upload-pack request: +'one compute step:' - C: 0032want <WANT #1>............................... - C: 0032want <WANT #2>............................... +C: Send one `$GIT_URL/git-upload-pack` request: + + C: 0032want <want #1>............................... + C: 0032want <want #2>............................... .... - C: 0032have <COMMON #1>............................. - C: 0032have <COMMON #2>............................. + C: 0032have <common #1>............................. + C: 0032have <common #2>............................. .... - C: 0032have <HAVE #1>............................... - C: 0032have <HAVE #2>............................... + C: 0032have <have #1>............................... + C: 0032have <have #2>............................... .... C: 0000 - The stream is organized into "commands", with each command - appearing by itself in a pkt-line. Within a command line - the text leading up to the first space is the command name, - and the remainder of the line to the first LF is the value. - Command lines are terminated with an LF as the last byte of - the pkt-line value. +The stream is organized into "commands", with each command +appearing by itself in a pkt-line. Within a command line +the text leading up to the first space is the command name, +and the remainder of the line to the first LF is the value. +Command lines are terminated with an LF as the last byte of +the pkt-line value. - Commands MUST appear in the following order, if they appear - at all in the request stream: +Commands MUST appear in the following order, if they appear +at all in the request stream: - * want - * have +* "want" +* "have" - The stream is terminated by a pkt-line flush ("0000"). +The stream is terminated by a pkt-line flush (`0000`). - A single "want" or "have" command MUST have one hex formatted - SHA-1 as its value. Multiple SHA-1s MUST be sent by sending - multiple commands. +A single "want" or "have" command MUST have one hex formatted +SHA-1 as its value. Multiple SHA-1s MUST be sent by sending +multiple commands. - The HAVE list is created by popping the first 32 commits - from C_PENDING. Less can be supplied if C_PENDING empties. +The `have` list is created by popping the first 32 commits +from `c_pending`. Less can be supplied if `c_pending` empties. - If the client has sent 256 HAVE commits and has not yet - received one of those back from S_COMMON, or the client has - emptied C_PENDING it SHOULD include a "done" command to let - the server know it won't proceed: +If the client has sent 256 "have" commits and has not yet +received one of those back from `s_common`, or the client has +emptied `c_pending` it SHOULD include a "done" command to let +the server know it won't proceed: C: 0009done - (s) Parse the git-upload-pack request: - - Verify all objects in WANT are directly reachable from refs. - - The server MAY walk backwards through history or through - the reflog to permit slightly stale requests. +S: Parse the git-upload-pack request: - If no WANT objects are received, send an error: +Verify all objects in `want` are directly reachable from refs. -TODO: Define error if no want lines are requested. +The server MAY walk backwards through history or through +the reflog to permit slightly stale requests. - If any WANT object is not reachable, send an error: +If no "want" objects are received, send an error: +TODO: Define error if no "want" lines are requested. -TODO: Define error if an invalid want is requested. +If any "want" object is not reachable, send an error: +TODO: Define error if an invalid "want" is requested. - Create an empty list, S_COMMON. +Create an empty list, `s_common`. - If 'have' was sent: +If "have" was sent: - Loop through the objects in the order supplied by the client. - For each object, if the server has the object reachable from - a ref, add it to S_COMMON. If a commit is added to S_COMMON, - do not add any ancestors, even if they also appear in HAVE. +Loop through the objects in the order supplied by the client. - (s) Send the git-upload-pack response: +For each object, if the server has the object reachable from +a ref, add it to `s_common`. If a commit is added to `s_common`, +do not add any ancestors, even if they also appear in `have`. - If the server has found a closed set of objects to pack or the - request ends with "done", it replies with the pack. +S: Send the git-upload-pack response: +If the server has found a closed set of objects to pack or the +request ends with "done", it replies with the pack. TODO: Document the pack based response - S: PACK... - The returned stream is the side-band-64k protocol supported - by the git-upload-pack service, and the pack is embedded into - stream 1. Progress messages from the server side MAY appear - in stream 2. + S: PACK... - Here a "closed set of objects" is defined to have at least - one path from every WANT to at least one COMMON object. +The returned stream is the side-band-64k protocol supported +by the git-upload-pack service, and the pack is embedded into +stream 1. Progress messages from the server side MAY appear +in stream 2. - If the server needs more information, it replies with a - status continue response: +Here a "closed set of objects" is defined to have at least +one path from every "want" to at least one "common" object. +If the server needs more information, it replies with a +status continue response: TODO: Document the non-pack response - (c) Parse the upload-pack response: - -TODO: Document parsing response +C: Parse the upload-pack response: + TODO: Document parsing response - Do another compute step. +'Do another compute step.' Smart Service git-receive-pack ------------------------------ -This service reads from the repository pointed to by $GIT_URL. +This service reads from the repository pointed to by `$GIT_URL`. Clients MUST first perform ref discovery with -'$GIT_URL/info/refs?service=git-receive-pack'. +`$GIT_URL/info/refs?service=git-receive-pack`. C: POST $GIT_URL/git-receive-pack HTTP/1.0 C: Content-Type: application/x-git-receive-pack-request |