summaryrefslogtreecommitdiff
path: root/Documentation/technical
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/technical')
-rw-r--r--Documentation/technical/api-allocation-growing.txt14
-rw-r--r--Documentation/technical/api-argv-array.txt8
-rw-r--r--Documentation/technical/api-builtin.txt6
-rw-r--r--Documentation/technical/api-config.txt10
-rw-r--r--Documentation/technical/api-credentials.txt22
-rw-r--r--Documentation/technical/api-directory-listing.txt60
-rw-r--r--Documentation/technical/api-history-graph.txt10
-rw-r--r--Documentation/technical/api-index-skel.txt4
-rw-r--r--Documentation/technical/api-parse-options.txt20
-rw-r--r--Documentation/technical/api-ref-iteration.txt2
-rw-r--r--Documentation/technical/api-remote.txt4
-rw-r--r--Documentation/technical/api-revision-walking.txt2
-rw-r--r--Documentation/technical/api-run-command.txt6
-rw-r--r--Documentation/technical/api-setup.txt38
-rw-r--r--Documentation/technical/api-sha1-array.txt4
-rw-r--r--Documentation/technical/api-strbuf.txt31
-rw-r--r--Documentation/technical/api-string-list.txt13
-rw-r--r--Documentation/technical/http-protocol.txt503
-rw-r--r--Documentation/technical/index-format.txt16
-rw-r--r--Documentation/technical/pack-format.txt22
-rw-r--r--Documentation/technical/pack-heuristics.txt22
-rw-r--r--Documentation/technical/pack-protocol.txt3
-rw-r--r--Documentation/technical/protocol-capabilities.txt40
-rw-r--r--Documentation/technical/racy-git.txt34
-rw-r--r--Documentation/technical/shallow.txt7
25 files changed, 773 insertions, 128 deletions
diff --git a/Documentation/technical/api-allocation-growing.txt b/Documentation/technical/api-allocation-growing.txt
index 43dbe09f73..542946b1ba 100644
--- a/Documentation/technical/api-allocation-growing.txt
+++ b/Documentation/technical/api-allocation-growing.txt
@@ -5,7 +5,9 @@ Dynamically growing an array using realloc() is error prone and boring.
Define your array with:
-* a pointer (`ary`) that points at the array, initialized to `NULL`;
+* a pointer (`item`) that points at the array, initialized to `NULL`
+ (although please name the variable based on its contents, not on its
+ type);
* an integer variable (`alloc`) that keeps track of how big the current
allocation is, initialized to `0`;
@@ -13,22 +15,22 @@ Define your array with:
* another integer variable (`nr`) to keep track of how many elements the
array currently has, initialized to `0`.
-Then before adding `n`th element to the array, call `ALLOC_GROW(ary, n,
+Then before adding `n`th element to the item, call `ALLOC_GROW(item, n,
alloc)`. This ensures that the array can hold at least `n` elements by
calling `realloc(3)` and adjusting `alloc` variable.
------------
-sometype *ary;
+sometype *item;
size_t nr;
size_t alloc
for (i = 0; i < nr; i++)
- if (we like ary[i] already)
+ if (we like item[i] already)
return;
/* we did not like any existing one, so add one */
-ALLOC_GROW(ary, nr + 1, alloc);
-ary[nr++] = value you like;
+ALLOC_GROW(item, nr + 1, alloc);
+item[nr++] = value you like;
------------
You are responsible for updating the `nr` variable.
diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt
index 1a797812fb..a6b7d83a8e 100644
--- a/Documentation/technical/api-argv-array.txt
+++ b/Documentation/technical/api-argv-array.txt
@@ -53,3 +53,11 @@ Functions
`argv_array_clear`::
Free all memory associated with the array and return it to the
initial, empty state.
+
+`argv_array_detach`::
+ Detach the argv array from the `struct argv_array`, transferring
+ ownership of the allocated array and strings.
+
+`argv_array_free_detached`::
+ Free the memory allocated by a `struct argv_array` that was later
+ detached and is now no longer needed.
diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt
index b0cafe87be..f3c1357b7c 100644
--- a/Documentation/technical/api-builtin.txt
+++ b/Documentation/technical/api-builtin.txt
@@ -5,7 +5,7 @@ Adding a new built-in
---------------------
There are 4 things to do to add a built-in command implementation to
-git:
+Git:
. Define the implementation of the built-in command `foo` with
signature:
@@ -23,7 +23,7 @@ where options is the bitwise-or of:
`RUN_SETUP`::
- Make sure there is a git directory to work on, and if there is a
+ Make sure there is a Git directory to work on, and 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.
@@ -39,7 +39,7 @@ where options is the bitwise-or of:
on bare repositories.
This only makes sense when `RUN_SETUP` is also set.
-. Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`.
+. Add `builtin/foo.o` to `BUILTIN_OBJS` in `Makefile`.
Additionally, if `foo` is a new command, there are 3 more things to do:
diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
index edf8dfb99b..230b3a0f60 100644
--- a/Documentation/technical/api-config.txt
+++ b/Documentation/technical/api-config.txt
@@ -1,7 +1,7 @@
config API
==========
-The config API gives callers a way to access git configuration files
+The config API gives callers a way to access Git configuration files
(and files which have the same syntax). See linkgit:git-config[1] for a
discussion of the config file syntax.
@@ -12,7 +12,7 @@ Config files are parsed linearly, and each variable found is passed to a
caller-provided callback function. The callback function is responsible
for any actions to be taken on the config option, and is free to ignore
some options. It is not uncommon for the configuration to be parsed
-several times during the run of a git program, with different callbacks
+several times during the run of a Git program, with different callbacks
picking out different variables useful to themselves.
A config callback function takes three parameters:
@@ -36,7 +36,7 @@ Basic Config Querying
---------------------
Most programs will simply want to look up variables in all config files
-that git knows about, using the normal precedence rules. To do this,
+that Git knows about, using the normal precedence rules. To do this,
call `git_config` with a callback function and void data pointer.
`git_config` will read all config sources in order of increasing
@@ -49,7 +49,7 @@ value is left at the end).
The `git_config_with_options` function lets the caller examine config
while adjusting some of the default behavior of `git_config`. It should
-almost never be used by "regular" git code that is looking up
+almost never be used by "regular" Git code that is looking up
configuration variables. It is intended for advanced callers like
`git-config`, which are intentionally tweaking the normal config-lookup
process. It takes two extra parameters:
@@ -66,7 +66,7 @@ Regular `git_config` defaults to `1`.
There is a special version of `git_config` called `git_config_early`.
This version takes an additional parameter to specify the repository
config, instead of having it looked up via `git_path`. This is useful
-early in a git program before the repository has been found. Unless
+early in a Git program before the repository has been found. Unless
you're working with early setup code, you probably don't want to use
this.
diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index 5977b58e57..c1b42a40d3 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt
@@ -7,9 +7,9 @@ world can take many forms, in this document the word "credential" always
refers to a username and password pair).
This document describes two interfaces: the C API that the credential
-subsystem provides to the rest of git, and the protocol that git uses to
+subsystem provides to the rest of Git, and the protocol that Git uses to
communicate with system-specific "credential helpers". If you are
-writing git code that wants to look up or prompt for credentials, see
+writing Git code that wants to look up or prompt for credentials, see
the section "C API" below. If you want to write your own helper, see
the section on "Credential Helpers" below.
@@ -18,7 +18,7 @@ Typical setup
------------
+-----------------------+
-| git code (C) |--- to server requiring --->
+| Git code (C) |--- to server requiring --->
| | authentication
|.......................|
| C credential API |--- prompt ---> User
@@ -27,11 +27,11 @@ Typical setup
| pipe |
| v
+-----------------------+
-| git credential helper |
+| Git credential helper |
+-----------------------+
------------
-The git code (typically a remote-helper) will call the C API to obtain
+The Git code (typically a remote-helper) will call the C API to obtain
credential data like a login/password pair (credential_fill). The
API will itself call a remote helper (e.g. "git credential-cache" or
"git credential-store") that may retrieve credential data from a
@@ -42,7 +42,7 @@ contacting the server, and does the actual authentication.
C API
-----
-The credential C API is meant to be called by git code which needs to
+The credential C API is meant to be called by Git code which needs to
acquire or store a credential. It is centered around an object
representing a single credential and provides three basic operations:
fill (acquire credentials by calling helpers and/or prompting the user),
@@ -160,7 +160,7 @@ int foo_login(struct foo_connection *f)
break;
default:
/*
- * Some other error occured. We don't know if the
+ * Some other error occurred. We don't know if the
* credential is good or bad, so report nothing to the
* credential subsystem.
*/
@@ -177,14 +177,14 @@ int foo_login(struct foo_connection *f)
Credential Helpers
------------------
-Credential helpers are programs executed by git to fetch or save
+Credential helpers are programs executed by Git to fetch or save
credentials from and to long-term storage (where "long-term" is simply
-longer than a single git process; e.g., credentials may be stored
+longer than a single Git process; e.g., credentials may be stored
in-memory for a few minutes, or indefinitely on disk).
Each helper is specified by a single string in the configuration
variable `credential.helper` (and others, see linkgit:git-config[1]).
-The string is transformed by git into a command to be executed using
+The string is transformed by Git into a command to be executed using
these rules:
1. If the helper string begins with "!", it is considered a shell
@@ -248,7 +248,7 @@ FORMAT` in linkgit:git-credential[7] for a detailed specification).
For a `get` operation, the helper should produce a list of attributes
on stdout in the same format. A helper is free to produce a subset, or
even no values at all if it has nothing useful to provide. Any provided
-attributes will overwrite those already known about by git.
+attributes will overwrite those already known about by Git.
For a `store` or `erase` operation, the helper's output is ignored.
If it fails to perform the requested operation, it may complain to
diff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt
index add6f435b5..7f8e78d916 100644
--- a/Documentation/technical/api-directory-listing.txt
+++ b/Documentation/technical/api-directory-listing.txt
@@ -9,37 +9,51 @@ Data structure
--------------
`struct dir_struct` structure is used to pass directory traversal
-options to the library and to record the paths discovered. The notable
-options are:
+options to the library and to record the paths discovered. A single
+`struct dir_struct` is used regardless of whether or not the traversal
+recursively descends into subdirectories.
+
+The notable options are:
`exclude_per_dir`::
The name of the file to be read in each directory for excluded
files (typically `.gitignore`).
-`collect_ignored`::
+`flags`::
+
+ A bit-field of options (the `*IGNORED*` flags are mutually exclusive):
+
+`DIR_SHOW_IGNORED`:::
+
+ Return just ignored files in `entries[]`, not untracked files.
+
+`DIR_SHOW_IGNORED_TOO`:::
- Include paths that are to be excluded in the result.
+ Similar to `DIR_SHOW_IGNORED`, but return ignored files in `ignored[]`
+ in addition to untracked files in `entries[]`.
-`show_ignored`::
+`DIR_COLLECT_IGNORED`:::
- The traversal is for finding just ignored files, not unignored
- files.
+ Special mode for git-add. Return ignored files in `ignored[]` and
+ untracked files in `entries[]`. Only returns ignored files that match
+ pathspec exactly (no wildcards). Does not recurse into ignored
+ directories.
-`show_other_directories`::
+`DIR_SHOW_OTHER_DIRECTORIES`:::
Include a directory that is not tracked.
-`hide_empty_directories`::
+`DIR_HIDE_EMPTY_DIRECTORIES`:::
Do not include a directory that is not tracked and is empty.
-`no_gitlinks`::
+`DIR_NO_GITLINKS`:::
- If set, recurse into a directory that looks like a git
+ If set, recurse into a directory that looks like a Git
directory. Otherwise it is shown as a directory.
-The result of the enumeration is left in these fields::
+The result of the enumeration is left in these fields:
`entries[]`::
@@ -54,6 +68,14 @@ The result of the enumeration is left in these fields::
Internal use; keeps track of allocation of `entries[]` array.
+`ignored[]`::
+
+ An array of `struct dir_entry`, used for ignored paths with the
+ `DIR_SHOW_IGNORED_TOO` and `DIR_COLLECT_IGNORED` flags.
+
+`ignored_nr`::
+
+ The number of members in `ignored[]` array.
Calling sequence
----------------
@@ -64,11 +86,13 @@ marked. If you to exclude files, make sure you have loaded index first.
* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0,
sizeof(dir))`.
-* Call `add_exclude()` to add single exclude pattern,
- `add_excludes_from_file()` to add patterns from a file
- (e.g. `.git/info/exclude`), and/or set `dir.exclude_per_dir`. A
- short-hand function `setup_standard_excludes()` can be used to set up
- the standard set of exclude settings.
+* To add single exclude pattern, call `add_exclude_list()` and then
+ `add_exclude()`.
+
+* To add patterns from a file (e.g. `.git/info/exclude`), call
+ `add_excludes_from_file()` , and/or set `dir.exclude_per_dir`. A
+ short-hand function `setup_standard_excludes()` can be used to set
+ up the standard set of exclude settings.
* Set options described in the Data Structure section above.
@@ -76,4 +100,6 @@ marked. If you to exclude files, make sure you have loaded index first.
* Use `dir.entries[]`.
+* Call `clear_directory()` when none of the contained elements are no longer in use.
+
(JC)
diff --git a/Documentation/technical/api-history-graph.txt b/Documentation/technical/api-history-graph.txt
index d6fc90ac7e..18142b6d29 100644
--- a/Documentation/technical/api-history-graph.txt
+++ b/Documentation/technical/api-history-graph.txt
@@ -33,11 +33,11 @@ The following utility functions are wrappers around `graph_next_line()` and
They can all be called with a NULL graph argument, in which case no graph
output will be printed.
-* `graph_show_commit()` calls `graph_next_line()` until it returns non-zero.
- This prints all graph lines up to, and including, the line containing this
- commit. Output is printed to stdout. The last line printed does not contain
- a terminating newline. This should not be called if the commit line has
- already been printed, or it will loop forever.
+* `graph_show_commit()` calls `graph_next_line()` and
+ `graph_is_commit_finished()` until one of them return non-zero. This prints
+ all graph lines up to, and including, the line containing this commit.
+ Output is printed to stdout. The last line printed does not contain a
+ terminating newline.
* `graph_show_oneline()` calls `graph_next_line()` and prints the result to
stdout. The line printed does not contain a terminating newline.
diff --git a/Documentation/technical/api-index-skel.txt b/Documentation/technical/api-index-skel.txt
index 730cfacf78..eda8c195c1 100644
--- a/Documentation/technical/api-index-skel.txt
+++ b/Documentation/technical/api-index-skel.txt
@@ -1,7 +1,7 @@
-GIT API Documents
+Git API Documents
=================
-GIT has grown a set of internal API over time. This collection
+Git has grown a set of internal API over time. This collection
documents them.
////////////////////////////////////////////////////////////////
diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index 3062389404..0be2b5159f 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -1,7 +1,7 @@
parse-options API
=================
-The parse-options API is used to parse and massage options in git
+The parse-options API is used to parse and massage options in Git
and to provide a usage help with consistent look.
Basics
@@ -41,6 +41,8 @@ The parse-options API allows:
* Boolean long options can be 'negated' (or 'unset') by prepending
`no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely,
options that begin with `no-` can be 'negated' by removing it.
+ Other long options can be unset (e.g., set string to NULL, set
+ integer to 0) by prepending `no-`.
* Options and non-option arguments can clearly be separated using the `--`
option, e.g. `-a -b --option -- --this-is-a-file` indicates that
@@ -174,6 +176,10 @@ There are some macros to easily define options:
Introduce an option with date argument, see `approxidate()`.
The timestamp is put into `int_var`.
+`OPT_EXPIRY_DATE(short, long, &int_var, description)`::
+ Introduce an option with expiry date argument, see `parse_expiry_date()`.
+ The timestamp is put into `int_var`.
+
`OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
Introduce an option with argument.
The argument will be fed into the function given by `func_ptr`
@@ -269,10 +275,10 @@ Examples
--------
See `test-parse-options.c` and
-`builtin-add.c`,
-`builtin-clone.c`,
-`builtin-commit.c`,
-`builtin-fetch.c`,
-`builtin-fsck.c`,
-`builtin-rm.c`
+`builtin/add.c`,
+`builtin/clone.c`,
+`builtin/commit.c`,
+`builtin/fetch.c`,
+`builtin/fsck.c`,
+`builtin/rm.c`
for real-world examples.
diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt
index dbbea95db7..aa1c50f181 100644
--- a/Documentation/technical/api-ref-iteration.txt
+++ b/Documentation/technical/api-ref-iteration.txt
@@ -35,7 +35,7 @@ Iteration functions
* `head_ref_submodule()`, `for_each_ref_submodule()`,
`for_each_ref_in_submodule()`, `for_each_tag_ref_submodule()`,
`for_each_branch_ref_submodule()`, `for_each_remote_ref_submodule()`
- do the same as the functions descibed above but for a specified
+ do the same as the functions described above but for a specified
submodule.
* `for_each_rawref()` can be used to learn about broken ref and symref.
diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt
index c54b17db69..4be87768f6 100644
--- a/Documentation/technical/api-remote.txt
+++ b/Documentation/technical/api-remote.txt
@@ -3,7 +3,7 @@ Remotes configuration API
The API in remote.h gives access to the configuration related to
remotes. It handles all three configuration mechanisms historically
-and currently used by git, and presents the information in a uniform
+and currently used by Git, and presents the information in a uniform
fashion. Note that the code also handles plain URLs without any
configuration, giving them just the default information.
@@ -45,7 +45,7 @@ struct remote
`receivepack`, `uploadpack`::
The configured helper programs to run on the remote side, for
- git-native protocols.
+ Git-native protocols.
`http_proxy`::
diff --git a/Documentation/technical/api-revision-walking.txt b/Documentation/technical/api-revision-walking.txt
index b7d0d9a8a7..55b878ade8 100644
--- a/Documentation/technical/api-revision-walking.txt
+++ b/Documentation/technical/api-revision-walking.txt
@@ -59,7 +59,7 @@ function.
`reset_revision_walk`::
Reset the flags used by the revision walking api. You can use
- this to do multiple sequencial revision walks.
+ this to do multiple sequential revision walks.
Data structures
---------------
diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt
index f18b4f4817..5d7d7f2d32 100644
--- a/Documentation/technical/api-run-command.txt
+++ b/Documentation/technical/api-run-command.txt
@@ -55,10 +55,8 @@ The functions above do the following:
non-zero.
. If the program terminated due to a signal, then the return value is the
- signal number - 128, ie. it is negative and so indicates an unusual
- condition; a diagnostic is printed. This return value can be passed to
- exit(2), which will report the same code to the parent process that a
- POSIX shell's $? would report for a program that died from the signal.
+ signal number + 128, ie. the same value that a POSIX shell's $? would
+ report. A diagnostic is printed.
`start_async`::
diff --git a/Documentation/technical/api-setup.txt b/Documentation/technical/api-setup.txt
index 4f63a04d7d..540e455689 100644
--- a/Documentation/technical/api-setup.txt
+++ b/Documentation/technical/api-setup.txt
@@ -8,6 +8,42 @@ Talk about
* is_inside_git_dir()
* is_inside_work_tree()
* setup_work_tree()
-* get_pathspec()
(Dscho)
+
+Pathspec
+--------
+
+See glossary-context.txt for the syntax of pathspec. In memory, a
+pathspec set is represented by "struct pathspec" and is prepared by
+parse_pathspec(). This function takes several arguments:
+
+- magic_mask specifies what features that are NOT supported by the
+ following code. If a user attempts to use such a feature,
+ parse_pathspec() can reject it early.
+
+- flags specifies other things that the caller wants parse_pathspec to
+ perform.
+
+- prefix and args come from cmd_* functions
+
+get_pathspec() is obsolete and should never be used in new code.
+
+parse_pathspec() helps catch unsupported features and reject them
+politely. At a lower level, different pathspec-related functions may
+not support the same set of features. Such pathspec-sensitive
+functions are guarded with GUARD_PATHSPEC(), which will die in an
+unfriendly way when an unsupported feature is requested.
+
+The command designers are supposed to make sure that GUARD_PATHSPEC()
+never dies. They have to make sure all unsupported features are caught
+by parse_pathspec(), not by GUARD_PATHSPEC. grepping GUARD_PATHSPEC()
+should give the designers all pathspec-sensitive codepaths and what
+features they support.
+
+A similar process is applied when a new pathspec magic is added. The
+designer lifts the GUARD_PATHSPEC restriction in the functions that
+support the new magic. At the same time (s)he has to make sure this
+new feature will be caught at parse_pathspec() in commands that cannot
+handle the new magic in some cases. grepping parse_pathspec() should
+help.
diff --git a/Documentation/technical/api-sha1-array.txt b/Documentation/technical/api-sha1-array.txt
index 45d1c517cd..3e75497a37 100644
--- a/Documentation/technical/api-sha1-array.txt
+++ b/Documentation/technical/api-sha1-array.txt
@@ -1,7 +1,7 @@
sha1-array API
==============
-The sha1-array API provides storage and manipulation of sets of SHA1
+The sha1-array API provides storage and manipulation of sets of SHA-1
identifiers. The emphasis is on storage and processing efficiency,
making them suitable for large lists. Note that the ordering of items is
not preserved over some operations.
@@ -11,7 +11,7 @@ Data Structures
`struct sha1_array`::
- A single array of SHA1 hashes. This should be initialized by
+ A single array of SHA-1 hashes. This should be initialized by
assignment from `SHA1_ARRAY_INIT`. The `sha1` member contains
the actual data. The `nr` member contains the number of items in
the set. The `alloc` and `sorted` members are used internally,
diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt
index 95a8bf3846..3350d97dda 100644
--- a/Documentation/technical/api-strbuf.txt
+++ b/Documentation/technical/api-strbuf.txt
@@ -156,6 +156,11 @@ then they will free() it.
Remove the bytes between `pos..pos+len` and replace it with the given
data.
+`strbuf_add_commented_lines`::
+
+ Add a NUL-terminated string to the buffer. Each line will be prepended
+ by a comment character and a blank.
+
`strbuf_add`::
Add data of given length to the buffer.
@@ -225,10 +230,20 @@ which can be used by the programmer of the callback as she sees fit.
destination. This is useful for literal data to be fed to either
strbuf_expand or to the *printf family of functions.
+`strbuf_humanise_bytes`::
+
+ Append the given byte size as a human-readable string (i.e. 12.23 KiB,
+ 3.50 MiB).
+
`strbuf_addf`::
Add a formatted string to the buffer.
+`strbuf_commented_addf`::
+
+ Add a formatted string prepended by a comment character and a
+ blank to the buffer.
+
`strbuf_fread`::
Read a given size of data from a FILE* pointer to the buffer.
@@ -279,6 +294,22 @@ same behaviour as well.
Strip whitespace from a buffer. The second parameter controls if
comments are considered contents to be removed or not.
+`strbuf_split_buf`::
+`strbuf_split_str`::
+`strbuf_split_max`::
+`strbuf_split`::
+
+ Split a string or strbuf into a list of strbufs at a specified
+ terminator character. The returned substrings include the
+ terminator characters. Some of these functions take a `max`
+ parameter, which, if positive, limits the output to that
+ number of substrings.
+
+`strbuf_list_free`::
+
+ Free a list of strbufs (for example, the return values of the
+ `strbuf_split()` functions).
+
`launch_editor`::
Launch the user preferred editor to edit a file and fill the buffer
diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt
index 94d7a2bd99..20be348834 100644
--- a/Documentation/technical/api-string-list.txt
+++ b/Documentation/technical/api-string-list.txt
@@ -38,7 +38,8 @@ member (you need this if you add things later) and you should set the
`unsorted_string_list_delete_item`.
. Can remove items not matching a criterion from a sorted or unsorted
- list using `filter_string_list`.
+ list using `filter_string_list`, or remove empty strings using
+ `string_list_remove_empty_items`.
. Finally it should free the list using `string_list_clear`.
@@ -75,13 +76,11 @@ Functions
to be deleted. Preserve the order of the items that are
retained.
-`string_list_longest_prefix`::
+`string_list_remove_empty_items`::
- Return the longest string within a string_list that is a
- prefix (in the sense of prefixcmp()) of the specified string,
- or NULL if no such prefix exists. This function does not
- require the string_list to be sorted (it does a linear
- search).
+ Remove any empty strings from the list. If free_util is true,
+ call free() on the util members of any items that have to be
+ deleted. Preserve the order of the items that are retained.
`print_string_list`::
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
new file mode 100644
index 0000000000..a1173ee266
--- /dev/null
+++ b/Documentation/technical/http-protocol.txt
@@ -0,0 +1,503 @@
+HTTP transfer protocols
+=======================
+
+Git supports two HTTP based transfer protocols. A "dumb" protocol
+which requires only a standard HTTP server on the server end of the
+connection, and a "smart" protocol which requires a Git aware CGI
+(or server module). This document describes both protocols.
+
+As a design feature smart clients can automatically upgrade "dumb"
+protocol URLs to smart URLs. This permits all users to have the
+same published URL, and the peers automatically select the most
+efficient transport available to them.
+
+
+URL Format
+----------
+
+URLs for Git repositories accessed by HTTP use the standard HTTP
+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
+the http:// repository URL entered by the end-user.
+
+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.
+
+An example of a dumb client requesting for a loose object:
+
+ $GIT_URL: http://example.com:8080/git/repo.git
+ URL request: http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355
+
+An example of a smart request to a catch-all gateway:
+
+ $GIT_URL: http://example.com/daemon.cgi?svc=git&q=
+ URL request: http://example.com/daemon.cgi?svc=git&q=/info/refs&service=git-receive-pack
+
+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
+in any URL sent to a server. Compatible clients MUST expand
+'$GIT_URL/info/refs' as 'foo/info/refs' and not 'foo//info/refs'.
+
+
+Authentication
+--------------
+
+Standard HTTP authentication is used if authentication is required
+to access a repository, and MAY be configured and enforced by the
+HTTP server software.
+
+Because Git repositories are accessed by standard path components
+server administrators MAY use directory based permissions within
+their HTTP server to control repository access.
+
+Clients SHOULD support Basic authentication as described by RFC 2616.
+Servers SHOULD support Basic authentication by relying upon the
+HTTP server placed in front of the Git server software.
+
+Servers SHOULD NOT require HTTP cookies for the purposes of
+authentication or access control.
+
+Clients and servers MAY support other common forms of HTTP based
+authentication, such as Digest authentication.
+
+
+SSL
+---
+
+Clients and servers SHOULD support SSL, particularly to protect
+passwords when relying on Basic HTTP authentication.
+
+
+Session State
+-------------
+
+The Git over HTTP protocol (much like HTTP itself) is stateless
+from the perspective of the HTTP server side. All state MUST be
+retained and managed by the client process. This permits simple
+round-robin load-balancing on the server side, without needing to
+worry about state management.
+
+Clients MUST NOT require state management on the server side in
+order to function correctly.
+
+Servers MUST NOT require HTTP cookies in order to function correctly.
+Clients MAY store and forward HTTP cookies during request processing
+as described by RFC 2616 (HTTP/1.1). Servers SHOULD ignore any
+cookies sent by a client.
+
+
+General Request Processing
+--------------------------
+
+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
+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
+status code.
+
+Servers SHOULD support both HTTP 1.0 and HTTP 1.1.
+Servers SHOULD support chunked encoding for both request and response
+bodies.
+
+Clients SHOULD support both HTTP 1.0 and HTTP 1.1.
+Clients SHOULD support chunked encoding for both request and response
+bodies.
+
+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
+in the request and the entity has not changed. Clients MUST treat
+'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
+servers MUST follow RFC 2616 for cache controls.
+
+
+Discovering References
+----------------------
+
+All HTTP clients MUST begin either a fetch or a push exchange by
+discovering the references available on the remote repository.
+
+Dumb Clients
+~~~~~~~~~~~~
+
+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,
+without any search/query parameters.
+
+ C: GET $GIT_URL/info/refs HTTP/1.0
+
+ S: 200 OK
+ S:
+ S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint
+ S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master
+ S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0
+ 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.
+Clients MUST NOT attempt to validate the returned Content-Type.
+Dumb servers MUST NOT return a return type starting with
+"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'.
+
+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'.
+
+ info_refs = *( ref_record )
+ ref_record = any_ref / peeled_ref
+
+ any_ref = obj-id HTAB refname LF
+ peeled_ref = obj-id HTAB refname LF
+ obj-id HTAB refname "^{}" LF
+
+Smart Clients
+~~~~~~~~~~~~~
+
+HTTP clients that support the "smart" protocol (or both the
+"smart" and "dumb" protocols) MUST discover references by making
+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
+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:
+ S: 200 OK
+ S:
+ S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint
+ S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master
+ S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0
+ S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}
+
+ smart server reply:
+ S: 200 OK
+ S: Content-Type: application/x-git-upload-pack-advertisement
+ S: Cache-Control: no-cache
+ S:
+ S: 001e# service=git-upload-pack\n
+ S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n
+ S: 0042d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n
+ S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n
+ S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n
+
+Dumb Server Response
+^^^^^^^^^^^^^^^^^^^^
+Dumb servers MUST respond with the dumb server reply format.
+
+See the prior section under dumb clients for a more detailed
+description of the dumb server response.
+
+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.
+
+Otherwise, smart servers MUST respond with the smart server reply
+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'.
+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
+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 first five bytes of the response entity
+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".
+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
+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
+declarations behind a NUL on the first ref.
+
+ smart_reply = PKT-LINE("# service=$servicename" LF)
+ ref_list
+ "0000"
+ ref_list = empty_list / non_empty_list
+
+ empty_list = PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)
+
+ non_empty_list = PKT-LINE(obj-id SP name NUL cap_list LF)
+ *ref_record
+
+ cap-list = capability *(SP capability)
+ capability = 1*(LC_ALPHA / DIGIT / "-" / "_")
+ LC_ALPHA = %x61-7A
+
+ ref_record = any_ref / peeled_ref
+ any_ref = PKT-LINE(obj-id SP name LF)
+ 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.
+
+Clients MUST first perform ref discovery with
+'$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
+ C:
+ C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n
+ C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n
+ C: 0000
+
+ S: 200 OK
+ S: Content-Type: application/x-git-upload-pack-result
+ S: Cache-Control: no-cache
+ S:
+ S: ....ACK %s, continue
+ S: ....NAK
+
+Clients MUST NOT reuse or revalidate a cached reponse.
+Servers MUST include sufficient Cache-Control headers
+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
+appear in the response obtained through ref discovery unless the
+server advertises capability "allow-tip-sha1-in-want".
+
+ compute_request = want_list
+ have_list
+ request_end
+ request_end = "0000" / "done"
+
+ want_list = PKT-LINE(want NUL cap_list LF)
+ *(want_pkt)
+ want_pkt = PKT-LINE(want LF)
+ want = "want" SP id
+ cap_list = *(SP capability) SP
+
+ 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):
+
+ 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 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.
+
+ one compute step:
+ (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 <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.
+
+ Commands MUST appear in the following order, if they appear
+ at all in the request stream:
+
+ * want
+ * have
+
+ 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.
+
+ 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:
+
+ 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.
+
+ If no WANT objects are received, send an error:
+
+TODO: Define error if no want lines are 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.
+
+ 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.
+
+ (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.
+
+ 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
+
+ Do another compute step.
+
+
+Smart Service git-receive-pack
+------------------------------
+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'.
+
+ C: POST $GIT_URL/git-receive-pack HTTP/1.0
+ C: Content-Type: application/x-git-receive-pack-request
+ C:
+ C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status
+ C: 0000
+ C: PACK....
+
+ S: 200 OK
+ S: Content-Type: application/x-git-receive-pack-result
+ S: Cache-Control: no-cache
+ S:
+ S: ....
+
+Clients MUST NOT reuse or revalidate a cached reponse.
+Servers MUST include sufficient Cache-Control headers
+to prevent caching of the response.
+
+Servers SHOULD support all capabilities defined here.
+
+Clients MUST send at least one command in the request body.
+Within the command portion of the request body clients SHOULD send
+the id obtained through ref discovery as old_id.
+
+ update_request = command_list
+ "PACK" <binary data>
+
+ command_list = PKT-LINE(command NUL cap_list LF)
+ *(command_pkt)
+ command_pkt = PKT-LINE(command LF)
+ cap_list = *(SP capability) SP
+
+ command = create / delete / update
+ create = zero-id SP new_id SP name
+ delete = old_id SP zero-id SP name
+ update = old_id SP new_id SP name
+
+TODO: Document this further.
+
+
+References
+----------
+
+link:http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
+link:http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
+link:technical/pack-protocol.txt
+link:technical/protocol-capabilities.txt
diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
index 7324154838..f352a9b22e 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/technical/index-format.txt
@@ -1,7 +1,7 @@
-GIT index format
+Git index format
================
-== The git index file has the following format
+== The Git index file has the following format
All binary numbers are in network byte order. Version 2 is described
here unless stated otherwise.
@@ -12,7 +12,7 @@ GIT index format
The signature is { 'D', 'I', 'R', 'C' } (stands for "dircache")
4-byte version number:
- The current supported versions are 2 and 3.
+ The current supported versions are 2, 3 and 4.
32-bit number of index entries.
@@ -21,9 +21,9 @@ GIT index format
- Extensions
Extensions are identified by signature. Optional extensions can
- be ignored if GIT does not understand them.
+ be ignored if Git does not understand them.
- GIT currently supports cached tree and resolve undo extensions.
+ Git currently supports cached tree and resolve undo extensions.
4-byte extension signature. If the first byte is 'A'..'Z' the
extension is optional and can be ignored.
@@ -93,8 +93,8 @@ GIT index format
12-bit name length if the length is less than 0xFFF; otherwise 0xFFF
is stored in this field.
- (Version 3) A 16-bit field, only applicable if the "extended flag"
- above is 1, split into (high to low bits).
+ (Version 3 or later) A 16-bit field, only applicable if the
+ "extended flag" above is 1, split into (high to low bits).
1-bit reserved for future
@@ -175,7 +175,7 @@ GIT index format
A conflict is represented in the index as a set of higher stage entries.
When a conflict is resolved (e.g. with "git add path"), these higher
- stage entries will be removed and a stage-0 entry with proper resoluton
+ stage entries will be removed and a stage-0 entry with proper resolution
is added.
When these higher stage entries are removed, they are saved in the
diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt
index a7871fb865..8e5bf60be3 100644
--- a/Documentation/technical/pack-format.txt
+++ b/Documentation/technical/pack-format.txt
@@ -1,4 +1,4 @@
-GIT pack format
+Git pack format
===============
== pack-*.pack files have the following format:
@@ -9,7 +9,7 @@ GIT pack format
The signature is: {'P', 'A', 'C', 'K'}
4-byte version number (network byte order):
- GIT currently accepts version number 2 or 3 but
+ Git currently accepts version number 2 or 3 but
generates version 2 only.
4-byte number of objects contained in the pack (network byte order)
@@ -26,13 +26,15 @@ GIT pack format
(deltified representation)
n-byte type and length (3-bit type, (n-1)*7+4-bit length)
- 20-byte base object name
+ 20-byte base object name if OBJ_REF_DELTA or a negative relative
+ offset from the delta object's position in the pack if this
+ is an OBJ_OFS_DELTA object
compressed delta data
Observation: length of each object is encoded in a variable
length format and is not constrained to 32-bit or anything.
- - The trailer records 20-byte SHA1 checksum of all of the above.
+ - The trailer records 20-byte SHA-1 checksum of all of the above.
== Original (version 1) pack-*.idx files have the following format:
@@ -53,10 +55,10 @@ GIT pack format
- The file is concluded with a trailer:
- A copy of the 20-byte SHA1 checksum at the end of
+ A copy of the 20-byte SHA-1 checksum at the end of
corresponding packfile.
- 20-byte SHA1-checksum of all of the above.
+ 20-byte SHA-1-checksum of all of the above.
Pack Idx file:
@@ -104,7 +106,7 @@ Pack file entry: <+
If it is not DELTA, then deflated bytes (the size above
is the size before compression).
If it is REF_DELTA, then
- 20-byte base object name SHA1 (the size above is the
+ 20-byte base object name SHA-1 (the size above is the
size of the delta data that follows).
delta data, deflated.
If it is OFS_DELTA, then
@@ -133,7 +135,7 @@ Pack file entry: <+
- A 256-entry fan-out table just like v1.
- - A table of sorted 20-byte SHA1 object names. These are
+ - A table of sorted 20-byte SHA-1 object names. These are
packed together without offset values to reduce the cache
footprint of the binary search for a specific object name.
@@ -154,7 +156,7 @@ Pack file entry: <+
- The same trailer as a v1 pack file:
- A copy of the 20-byte SHA1 checksum at the end of
+ A copy of the 20-byte SHA-1 checksum at the end of
corresponding packfile.
- 20-byte SHA1-checksum of all of the above.
+ 20-byte SHA-1-checksum of all of the above.
diff --git a/Documentation/technical/pack-heuristics.txt b/Documentation/technical/pack-heuristics.txt
index f29ee074bf..b7bd95152e 100644
--- a/Documentation/technical/pack-heuristics.txt
+++ b/Documentation/technical/pack-heuristics.txt
@@ -5,11 +5,11 @@
Where do I go
to learn the details
- of git's packing heuristics?
+ of Git's packing heuristics?
Be careful what you ask!
-Followers of the git, please open the git IRC Log and turn to
+Followers of the Git, please open the Git IRC Log and turn to
February 10, 2006.
It's a rare occasion, and we are joined by the King Git Himself,
@@ -19,7 +19,7 @@ and seeks enlightenment. Others are present, but silent.
Let's listen in!
<njs`> Oh, here's a really stupid question -- where do I go to
- learn the details of git's packing heuristics? google avails
+ learn the details of Git's packing heuristics? google avails
me not, reading the source didn't help a lot, and wading
through the whole mailing list seems less efficient than any
of that.
@@ -37,7 +37,7 @@ Ah! Modesty after all.
<linus> njs, I don't think the docs exist. That's something where
I don't think anybody else than me even really got involved.
- Most of the rest of git others have been busy with (especially
+ Most of the rest of Git others have been busy with (especially
Junio), but packing nobody touched after I did it.
It's cryptic, yet vague. Linus in style for sure. Wise men
@@ -57,7 +57,7 @@ Bait...
And switch. That ought to do it!
- <linus> Remember: git really doesn't follow files. So what it does is
+ <linus> Remember: Git really doesn't follow files. So what it does is
- generate a list of all objects
- sort the list according to magic heuristics
- walk the list, using a sliding window, seeing if an object
@@ -89,7 +89,7 @@ Ah, grasshopper! And thus the enlightenment begins anew.
<linus> The "magic" is actually in theory totally arbitrary.
ANY order will give you a working pack, but no, it's not
- ordered by SHA1.
+ ordered by SHA-1.
Before talking about the ordering for the sliding delta
window, let's talk about the recency order. That's more
@@ -376,7 +376,7 @@ been detailed!
<njs`> (if only it happened more...)
<linus> Anyway, the pack-file could easily be denser still, but
- because it's used both for streaming (the git protocol) and
+ because it's used both for streaming (the Git protocol) and
for on-disk, it has a few pessimizations.
Actually, it is a made-up word. But it is a made-up word being
@@ -426,12 +426,12 @@ Gasp! OK, saved. That's a fair Engineering trade off. Close call!
In fact, Linus reflects on some Basic Engineering Fundamentals,
design options, etc.
- <linus> More importantly, they allow git to still _conceptually_
+ <linus> More importantly, they allow Git to still _conceptually_
never deal with deltas at all, and be a "whole object" store.
Which has some problems (we discussed bad huge-file
- behaviour on the git lists the other day), but it does mean
- that the basic git concepts are really really simple and
+ behaviour on the Git lists the other day), but it does mean
+ that the basic Git concepts are really really simple and
straightforward.
It's all been quite stable.
@@ -455,6 +455,6 @@ Nuff said.
<njs`> :-)
<njs`> appreciate the infodump, I really was failing to find the
- details on git packs :-)
+ details on Git packs :-)
And now you know the rest of the story.
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index f1a51edf47..b898e97988 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -228,8 +228,7 @@ obtained through ref discovery.
The client MUST write all obj-ids which it only has shallow copies
of (meaning that it does not have the parents of a commit) as
'shallow' lines so that the server is aware of the limitations of
-the client's history. Clients MUST NOT mention an obj-id which
-it does not know exists on the server.
+the client's history.
The client now sends the maximum commit history depth it wants for
this transaction, which is the number of commits it wants from the
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
index b15517fa06..fd8ffa5df3 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/technical/protocol-capabilities.txt
@@ -18,11 +18,12 @@ was sent. Server MUST NOT ignore capabilities that client requested
and server advertised. As a consequence of these rules, server MUST
NOT advertise capabilities it does not understand.
-The 'report-status' and 'delete-refs' capabilities are sent and
+The 'report-status', 'delete-refs', and 'quiet' capabilities are sent and
recognized by the receive-pack (push to server) process.
-The 'ofs-delta' capability is sent and recognized by both upload-pack
-and receive-pack protocols.
+The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized
+by both upload-pack and receive-pack protocols. The 'agent' capability
+may optionally be sent in both protocols.
All other capabilities are only recognized by the upload-pack (fetch
from server) process.
@@ -123,6 +124,20 @@ Server can send, and client understand PACKv2 with delta referring to
its base by position in pack rather than by an obj-id. That is, they can
send/read OBJ_OFS_DELTA (aka type 6) in a packfile.
+agent
+-----
+
+The server may optionally send a capability of the form `agent=X` to
+notify the client that the server is running version `X`. The client may
+optionally return its own agent string by responding with an `agent=Y`
+capability (but it MUST NOT do so if the server did not mention the
+agent capability). The `X` and `Y` strings may contain any printable
+ASCII characters except space (i.e., the byte range 32 < x < 127), and
+are typically of the form "package/version" (e.g., "git/1.8.3.1"). The
+agent strings are purely informative for statistics and debugging
+purposes, and MUST NOT be used to programatically assume the presence
+or absence of particular features.
+
shallow
-------
@@ -168,7 +183,7 @@ of whether or not there are tags available.
report-status
-------------
-The upload-pack process can receive a 'report-status' capability,
+The receive-pack process can receive a 'report-status' capability,
which tells it that the client wants a report of what happened after
a packfile upload and reference update. If the pushing client requests
this capability, after unpacking and updating references the server
@@ -185,3 +200,20 @@ it is capable of accepting a zero-id value as the target
value of a reference update. It is not sent back by the client, it
simply informs the client that it can be sent zero-id values
to delete references.
+
+quiet
+-----
+
+If the receive-pack server advertises the 'quiet' capability, it is
+capable of silencing human-readable progress output which otherwise may
+be shown when processing the received pack. A send-pack client should
+respond with the 'quiet' capability to suppress server-side progress
+reporting if the local progress reporting is also being suppressed
+(e.g., via `push -q`, or if stderr does not go to a tty).
+
+allow-tip-sha1-in-want
+----------------------
+
+If the upload-pack server advertises this capability, fetch-pack may
+send "want" lines with SHA-1s that exist at the server but are not
+advertised by upload-pack.
diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt
index 53aa0c82c2..242a044db9 100644
--- a/Documentation/technical/racy-git.txt
+++ b/Documentation/technical/racy-git.txt
@@ -1,21 +1,21 @@
-Use of index and Racy git problem
+Use of index and Racy Git problem
=================================
Background
----------
-The index is one of the most important data structures in git.
+The index is one of the most important data structures in Git.
It represents a virtual working tree state by recording list of
paths and their object names and serves as a staging area to
write out the next tree object to be committed. The state is
"virtual" in the sense that it does not necessarily have to, and
often does not, match the files in the working tree.
-There are cases git needs to examine the differences between the
+There are cases Git needs to examine the differences between the
virtual working tree state in the index and the files in the
working tree. The most obvious case is when the user asks `git
diff` (or its low level implementation, `git diff-files`) or
-`git-ls-files --modified`. In addition, git internally checks
+`git-ls-files --modified`. In addition, Git internally checks
if the files in the working tree are different from what are
recorded in the index to avoid stomping on local changes in them
during patch application, switching branches, and merging.
@@ -24,16 +24,16 @@ In order to speed up this comparison between the files in the
working tree and the index entries, the index entries record the
information obtained from the filesystem via `lstat(2)` system
call when they were last updated. When checking if they differ,
-git first runs `lstat(2)` on the files and compares the result
+Git first runs `lstat(2)` on the files and compares the result
with this information (this is what was originally done by the
`ce_match_stat()` function, but the current code does it in
`ce_match_stat_basic()` function). If some of these "cached
-stat information" fields do not match, git can tell that the
+stat information" fields do not match, Git can tell that the
files are modified without even looking at their contents.
Note: not all members in `struct stat` obtained via `lstat(2)`
are used for this comparison. For example, `st_atime` obviously
-is not useful. Currently, git compares the file type (regular
+is not useful. Currently, Git compares the file type (regular
files vs symbolic links) and executable bits (only for regular
files) from `st_mode` member, `st_mtime` and `st_ctime`
timestamps, `st_uid`, `st_gid`, `st_ino`, and `st_size` members.
@@ -46,10 +46,10 @@ because in-core timestamps can have finer granularity than
on-disk timestamps, resulting in meaningless changes when an
inode is evicted from the inode cache. See commit 8ce13b0
of git://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git
-([PATCH] Sync in core time granuality with filesystems,
+([PATCH] Sync in core time granularity with filesystems,
2005-01-04).
-Racy git
+Racy Git
--------
There is one slight problem with the optimization based on the
@@ -67,13 +67,13 @@ timestamp does not change, after this sequence, the cached stat
information the index entry records still exactly match what you
would see in the filesystem, even though the file `foo` is now
different.
-This way, git can incorrectly think files in the working tree
+This way, Git can incorrectly think files in the working tree
are unmodified even though they actually are. This is called
-the "racy git" problem (discovered by Pasky), and the entries
+the "racy Git" problem (discovered by Pasky), and the entries
that appear clean when they may not be because of this problem
are called "racily clean".
-To avoid this problem, git does two things:
+To avoid this problem, Git does two things:
. When the cached stat information says the file has not been
modified, and the `st_mtime` is the same as (or newer than)
@@ -116,7 +116,7 @@ timestamp comparison check done with the former logic anymore.
The latter makes sure that the cached stat information for `foo`
would never match with the file in the working tree, so later
checks by `ce_match_stat_basic()` would report that the index entry
-does not match the file and git does not have to fall back on more
+does not match the file and Git does not have to fall back on more
expensive `ce_modified_check_fs()`.
@@ -135,9 +135,9 @@ them, and give the same timestamp to the index file:
$ git ls-files | git update-index --stdin
$ touch -r .datestamp .git/index
-This will make all index entries racily clean. The linux-2.6
-project, for example, there are over 20,000 files in the working
-tree. On my Athlon 64 X2 3800+, after the above:
+This will make all index entries racily clean. The linux project, for
+example, there are over 20,000 files in the working tree. On my
+Athlon 64 X2 3800+, after the above:
$ /usr/bin/time git diff-files
1.68user 0.54system 0:02.22elapsed 100%CPU (0avgtext+0avgdata 0maxresident)k
@@ -159,7 +159,7 @@ of the cached stat information.
Avoiding runtime penalty
------------------------
-In order to avoid the above runtime penalty, post 1.4.2 git used
+In order to avoid the above runtime penalty, post 1.4.2 Git used
to have a code that made sure the index file
got timestamp newer than the youngest files in the index when
there are many young files with the same timestamp as the
diff --git a/Documentation/technical/shallow.txt b/Documentation/technical/shallow.txt
index 0502a5471e..5183b15422 100644
--- a/Documentation/technical/shallow.txt
+++ b/Documentation/technical/shallow.txt
@@ -8,7 +8,7 @@ repo, and therefore grafts are introduced pretending that
these commits have no parents.
*********************************************************
-The basic idea is to write the SHA1s of shallow commits into
+The basic idea is to write the SHA-1s of shallow commits into
$GIT_DIR/shallow, and handle its contents like the contents
of $GIT_DIR/info/grafts (with the difference that shallow
cannot contain parent information).
@@ -18,7 +18,7 @@ even the config, since the user should not touch that file
at all (even throughout development of the shallow clone, it
was never manually edited!).
-Each line contains exactly one SHA1. When read, a commit_graft
+Each line contains exactly one SHA-1. When read, a commit_graft
will be constructed, which has nr_parent < 0 to make it easier
to discern from user provided grafts.
@@ -53,3 +53,6 @@ It also writes an appropriate $GIT_DIR/shallow.
You can deepen a shallow repository with "git-fetch --depth 20
repo branch", which will fetch branch from repo, but stop at depth
20, updating $GIT_DIR/shallow.
+
+The special depth 2147483647 (or 0x7fffffff, the largest positive
+number a signed 32-bit integer can contain) means infinite depth.