path: root/Documentation/technical
diff options
Diffstat (limited to 'Documentation/technical')
10 files changed, 173 insertions, 371 deletions
diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index c1b42a4..e44426d 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt
@@ -248,7 +248,10 @@ 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. If a helper
+outputs a `quit` attribute with a value of `true` or `1`, no further
+helpers will be consulted, nor will the user be prompted (if no
+credential has been provided, the operation will then fail).
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-error-handling.txt b/Documentation/technical/api-error-handling.txt
new file mode 100644
index 0000000..ceeedd4
--- /dev/null
+++ b/Documentation/technical/api-error-handling.txt
@@ -0,0 +1,75 @@
+Error reporting in git
+`die`, `usage`, `error`, and `warning` report errors of various
+- `die` is for fatal application errors. It prints a message to
+ the user and exits with status 128.
+- `usage` is for errors in command line usage. After printing its
+ message, it exits with status 129. (See also `usage_with_options`
+ in the link:api-parse-options.html[parse-options API].)
+- `error` is for non-fatal library errors. It prints a message
+ to the user and returns -1 for convenience in signaling the error
+ to the caller.
+- `warning` is for reporting situations that probably should not
+ occur but which the user (and Git) can continue to work around
+ without running into too many problems. Like `error`, it
+ returns -1 after reporting the situation to the caller.
+Customizable error handlers
+The default behavior of `die` and `error` is to write a message to
+stderr and then exit or return as appropriate. This behavior can be
+overridden using `set_die_routine` and `set_error_routine`. For
+example, "git daemon" uses set_die_routine to write the reason `die`
+was called to syslog before exiting.
+Library errors
+Functions return a negative integer on error. Details beyond that
+vary from function to function:
+- Some functions return -1 for all errors. Others return a more
+ specific value depending on how the caller might want to react
+ to the error.
+- Some functions report the error to stderr with `error`,
+ while others leave that for the caller to do.
+- errno is not meaningful on return from most functions (except
+ for thin wrappers for system calls).
+Check the function's API documentation to be sure.
+Caller-handled errors
+An increasing number of functions take a parameter 'struct strbuf *err'.
+On error, such functions append a message about what went wrong to the
+'err' strbuf. The message is meant to be complete enough to be passed
+to `die` or `error` as-is. For example:
+ if (ref_transaction_commit(transaction, &err))
+ die("%s", err.buf);
+The 'err' parameter will be untouched if no error occurred, so multiple
+function calls can be chained:
+ t = ref_transaction_begin(&err);
+ if (!t ||
+ ref_transaction_update(t, "HEAD", ..., &err) ||
+ ret_transaction_commit(t, &err))
+ die("%s", err.buf);
+The 'err' parameter must be a pointer to a valid strbuf. To silence
+a message, pass a strbuf that is explicitly ignored:
+ if (thing_that_can_fail_in_an_ignorable_way(..., &err))
+ /* This failure is okay. */
+ strbuf_reset(&err);
diff --git a/Documentation/technical/api-ref-iteration.txt b/Documentation/technical/api-ref-iteration.txt
index 02adfd4..37379d8 100644
--- a/Documentation/technical/api-ref-iteration.txt
+++ b/Documentation/technical/api-ref-iteration.txt
@@ -6,7 +6,7 @@ Iteration of refs is done by using an iterate function which will call a
callback function for every ref. The callback function has this
- int handle_one_ref(const char *refname, const unsigned char *sha1,
+ int handle_one_ref(const char *refname, const struct object_id *oid,
int flags, void *cb_data);
There are different kinds of iterate functions which all take a
diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt
index 5d245aa..2cfdd22 100644
--- a/Documentation/technical/api-remote.txt
+++ b/Documentation/technical/api-remote.txt
@@ -97,10 +97,6 @@ It contains:
The name of the remote listed in the configuration.
- The struct remote for that remote.
An array of the "merge" lines in the configuration.
diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt
deleted file mode 100644
index cca6543..0000000
--- a/Documentation/technical/api-strbuf.txt
+++ /dev/null
@@ -1,351 +0,0 @@
-strbuf API
-strbuf's are meant to be used with all the usual C string and memory
-APIs. Given that the length of the buffer is known, it's often better to
-use the mem* functions than a str* one (memchr vs. strchr e.g.).
-Though, one has to be careful about the fact that str* functions often
-stop on NULs and that strbufs may have embedded NULs.
-A strbuf is NUL terminated for convenience, but no function in the
-strbuf API actually relies on the string being free of NULs.
-strbufs have some invariants that are very important to keep in mind:
-. The `buf` member is never NULL, so it can be used in any usual C
-string operations safely. strbuf's _have_ to be initialized either by
-`strbuf_init()` or by `= STRBUF_INIT` before the invariants, though.
-Do *not* assume anything on what `buf` really is (e.g. if it is
-allocated memory or not), use `strbuf_detach()` to unwrap a memory
-buffer from its strbuf shell in a safe way. That is the sole supported
-way. This will give you a malloced buffer that you can later `free()`.
-However, it is totally safe to modify anything in the string pointed by
-the `buf` member, between the indices `0` and `len-1` (inclusive).
-. The `buf` member is a byte array that has at least `len + 1` bytes
- allocated. The extra byte is used to store a `'\0'`, allowing the
- `buf` member to be a valid C-string. Every strbuf function ensure this
- invariant is preserved.
-NOTE: It is OK to "play" with the buffer directly if you work it this
- way:
-strbuf_grow(sb, SOME_SIZE); <1>
-strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE);
-<1> Here, the memory array starting at `sb->buf`, and of length
-`strbuf_avail(sb)` is all yours, and you can be sure that
-`strbuf_avail(sb)` is at least `SOME_SIZE`.
-NOTE: `SOME_OTHER_SIZE` must be smaller or equal to `strbuf_avail(sb)`.
-Doing so is safe, though if it has to be done in many places, adding the
-missing API to the strbuf module is the way to go.
-WARNING: Do _not_ assume that the area that is yours is of size `alloc
-- 1` even if it's true in the current implementation. Alloc is somehow a
-"private" member that should not be messed with. Use `strbuf_avail()`
-Data structures
-* `struct strbuf`
-This is the string buffer structure. The `len` member can be used to
-determine the current length of the string, and `buf` member provides
-access to the string itself.
-* Life cycle
- Initialize the structure. The second parameter can be zero or a bigger
- number to allocate memory, in case you want to prevent further reallocs.
- Release a string buffer and the memory it used. You should not use the
- string buffer after using this function, unless you initialize it again.
- Detach the string from the strbuf and returns it; you now own the
- storage the string occupies and it is your responsibility from then on
- to release it with `free(3)` when you are done with it.
- Attach a string to a buffer. You should specify the string to attach,
- the current length of the string and the amount of allocated memory.
- The amount must be larger than the string length, because the string you
- pass is supposed to be a NUL-terminated string. This string _must_ be
- malloc()ed, and after attaching, the pointer cannot be relied upon
- anymore, and neither be free()d directly.
- Swap the contents of two string buffers.
-* Related to the size of the buffer
- Determine the amount of allocated but unused memory.
- Ensure that at least this amount of unused memory is available after
- `len`. This is used when you know a typical size for what you will add
- and want to avoid repetitive automatic resizing of the underlying buffer.
- This is never a needed operation, but can be critical for performance in
- some cases.
- Set the length of the buffer to a given value. This function does *not*
- allocate new memory, so you should not perform a `strbuf_setlen()` to a
- length that is larger than `len + strbuf_avail()`. `strbuf_setlen()` is
- just meant as a 'please fix invariants from this strbuf I just messed
- with'.
- Empty the buffer by setting the size of it to zero.
-* Related to the contents of the buffer
- Strip whitespace from the beginning and end of a string.
- Equivalent to performing `strbuf_rtrim()` followed by `strbuf_ltrim()`.
- Strip whitespace from the end of a string.
- Strip whitespace from the beginning of a string.
- Replace the contents of the strbuf with a reencoded form. Returns -1
- on error, 0 on success.
- Lowercase each character in the buffer using `tolower`.
- Compare two buffers. Returns an integer less than, equal to, or greater
- than zero if the first buffer is found, respectively, to be less than,
- to match, or be greater than the second buffer.
-* Adding data to the buffer
-NOTE: All of the functions in this section will grow the buffer as necessary.
-If they fail for some reason other than memory shortage and the buffer hadn't
-been allocated before (i.e. the `struct strbuf` was set to `STRBUF_INIT`),
-then they will free() it.
- Add a single character to the buffer.
- Add a character the specified number of times to the buffer.
- Insert data to the given position of the buffer. The remaining contents
- will be shifted, not overwritten.
- Remove given amount of data from a given position of the buffer.
- Remove the bytes between `pos..pos+len` and replace it with the given
- data.
- Add a NUL-terminated string to the buffer. Each line will be prepended
- by a comment character and a blank.
- Add data of given length to the buffer.
-Add a NUL-terminated string to the buffer.
-NOTE: This function will *always* be implemented as an inline or a macro
-that expands to:
-strbuf_add(..., s, strlen(s));
-Meaning that this is efficient to write things like:
-strbuf_addstr(sb, "immediate string");
- Copy the contents of another buffer at the end of the current one.
- Copy part of the buffer from a given position till a given length to the
- end of the buffer.
- This function can be used to expand a format string containing
- placeholders. To that end, it parses the string and calls the specified
- function for every percent sign found.
-The callback function is given a pointer to the character after the `%`
-and a pointer to the struct strbuf. It is expected to add the expanded
-version of the placeholder to the strbuf, e.g. to add a newline
-character if the letter `n` appears after a `%`. The function returns
-the length of the placeholder recognized and `strbuf_expand()` skips
-over it.
-The format `%%` is automatically expanded to a single `%` as a quoting
-mechanism; callers do not need to handle the `%` placeholder themselves,
-and the callback function will not be invoked for this placeholder.
-All other characters (non-percent and not skipped ones) are copied
-verbatim to the strbuf. If the callback returned zero, meaning that the
-placeholder is unknown, then the percent sign is copied, too.
-In order to facilitate caching and to make it possible to give
-parameters to the callback, `strbuf_expand()` passes a context pointer,
-which can be used by the programmer of the callback as she sees fit.
- Used as callback for `strbuf_expand()`, expects an array of
- struct strbuf_expand_dict_entry as context, i.e. pairs of
- placeholder and replacement string. The array needs to be
- terminated by an entry with placeholder set to NULL.
- Append the contents of one strbuf to another, quoting any
- percent signs ("%") into double-percents ("%%") in the
- destination. This is useful for literal data to be fed to either
- strbuf_expand or to the *printf family of functions.
- Append the given byte size as a human-readable string (i.e. 12.23 KiB,
- 3.50 MiB).
- Add a formatted string to the buffer.
- Add a formatted string prepended by a comment character and a
- blank to the buffer.
- Read a given size of data from a FILE* pointer to the buffer.
-NOTE: The buffer is rewound if the read fails. If -1 is returned,
-`errno` must be consulted, like you would do for `read(3)`.
-`strbuf_read()`, `strbuf_read_file()` and `strbuf_getline()` has the
-same behaviour as well.
- Read the contents of a given file descriptor. The third argument can be
- used to give a hint about the file size, to avoid reallocs.
- Read the contents of a file, specified by its path. The third argument
- can be used to give a hint about the file size, to avoid reallocs.
- Read the target of a symbolic link, specified by its path. The third
- argument can be used to give a hint about the size, to avoid reallocs.
- Read a line from a FILE *, overwriting the existing contents
- of the strbuf. The second argument specifies the line
- terminator character, typically `'\n'`.
- Reading stops after the terminator or at EOF. The terminator
- is removed from the buffer before returning. Returns 0 unless
- there was nothing left before EOF, in which case it returns `EOF`.
- Like `strbuf_getline`, but keeps the trailing terminator (if
- any) in the buffer.
- Like `strbuf_getwholeline`, but operates on a file descriptor.
- It reads one character at a time, so it is very slow. Do not
- use it unless you need the correct position in the file
- descriptor.
- Set the buffer to the path of the current working directory.
- Add a path to a buffer, converting a relative path to an
- absolute one in the process. Symbolic links are not
- resolved.
- Strip whitespace from a buffer. The second parameter controls if
- comments are considered contents to be removed or not.
- 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.
- Free a list of strbufs (for example, the return values of the
- `strbuf_split()` functions).
- Launch the user preferred editor to edit a file and fill the buffer
- with the file's contents upon the user completing their editing. The
- third argument can be used to set the environment which the editor is
- run in. If the buffer is NULL the editor is launched as usual but the
- file's contents are not read into the buffer upon completion.
diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt
index d51a657..c08402b 100644
--- a/Documentation/technical/api-string-list.txt
+++ b/Documentation/technical/api-string-list.txt
@@ -29,7 +29,7 @@ member (you need this if you add things later) and you should set the
`unsorted_string_list_has_string` and get it from the list using
`string_list_lookup` for sorted lists.
-. Can sort an unsorted list using `sort_string_list`.
+. Can sort an unsorted list using `string_list_sort`.
. Can remove duplicate items from a sorted list using
@@ -146,7 +146,7 @@ write `string_list_insert(...)->util = ...;`.
ownership of a malloc()ed string to a `string_list` that has
`strdup_string` set.
Sort the list's entries by string value in `strcmp()` order.
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
index 229f845..1c561bd 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/technical/http-protocol.txt
@@ -319,7 +319,8 @@ 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`.
+server advertises capability `allow-tip-sha1-in-want` or
compute_request = want_list
diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt
index 1250b5c..b7093af 100644
--- a/Documentation/technical/index-format.txt
+++ b/Documentation/technical/index-format.txt
@@ -207,7 +207,7 @@ Git index format
in a separate file. This extension records the changes to be made on
top of that to produce the final index.
- The signature for this extension is { 'l', 'i, 'n', 'k' }.
+ The signature for this extension is { 'l', 'i', 'n', 'k' }.
The extension consists of:
@@ -233,3 +233,65 @@ Git index format
The remaining index entries after replaced ones will be added to the
final index. These added entries are also sorted by entry name then
+== Untracked cache
+ Untracked cache saves the untracked file list and necessary data to
+ verify the cache. The signature for this extension is { 'U', 'N',
+ 'T', 'R' }.
+ The extension starts with
+ - A sequence of NUL-terminated strings, preceded by the size of the
+ sequence in variable width encoding. Each string describes the
+ environment where the cache can be used.
+ - Stat data of $GIT_DIR/info/exclude. See "Index entry" section from
+ ctime field until "file size".
+ - Stat data of core.excludesfile
+ - 32-bit dir_flags (see struct dir_struct)
+ - 160-bit SHA-1 of $GIT_DIR/info/exclude. Null SHA-1 means the file
+ does not exist.
+ - 160-bit SHA-1 of core.excludesfile. Null SHA-1 means the file does
+ not exist.
+ - NUL-terminated string of per-dir exclude file name. This usually
+ is ".gitignore".
+ - The number of following directory blocks, variable width
+ encoding. If this number is zero, the extension ends here with a
+ following NUL.
+ - A number of directory blocks in depth-first-search order, each
+ consists of
+ - The number of untracked entries, variable width encoding.
+ - The number of sub-directory blocks, variable width encoding.
+ - The directory name terminated by NUL.
+ - A number of untrached file/dir names terminated by NUL.
+The remaining data of each directory block is grouped by type:
+ - An ewah bitmap, the n-th bit marks whether the n-th directory has
+ valid untracked cache entries.
+ - An ewah bitmap, the n-th bit records "check-only" bit of
+ read_directory_recursive() for the n-th directory.
+ - An ewah bitmap, the n-th bit indicates whether SHA-1 and stat data
+ is valid for the n-th directory and exists in the next data.
+ - An array of stat data. The n-th data corresponds with the n-th
+ "one" bit in the previous ewah bitmap.
+ - An array of SHA-1. The n-th SHA-1 corresponds with the n-th "one" bit
+ in the previous ewah bitmap.
+ - One NUL.
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index 462e206..4064fc7 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -1,11 +1,11 @@
Packfile transfer protocols
-Git supports transferring data in packfiles over the ssh://, git:// and
+Git supports transferring data in packfiles over the ssh://, git://, http:// and
file:// transports. There exist two sets of protocols, one for pushing
data from a client to a server and another for fetching data from a
-server to a client. All three transports (ssh, git, file) use the same
-protocol to transfer data.
+server to a client. The three transports (ssh, git, file) use the same
+protocol to transfer data. http is documented in http-protocol.txt.
The processes invoked in the canonical Git implementation are 'upload-pack'
on the server side and 'fetch-pack' on the client side for fetching data;
@@ -465,7 +465,7 @@ contain all the objects that the server will need to complete the new
- update-request = *shallow ( command-list | push-cert ) [pack-file]
+ update-request = *shallow ( command-list | push-cert ) [packfile]
shallow = PKT-LINE("shallow" SP obj-id LF)
@@ -491,7 +491,7 @@ references.
*PKT-LINE(gpg-signature-lines LF)
PKT-LINE("push-cert-end" LF)
- pack-file = "PACK" 28*(OCTET)
+ packfile = "PACK" 28*(OCTET)
If the receiving end does not support delete-refs, the sending end MUST
@@ -502,11 +502,11 @@ MUST NOT send a push-cert command. When a push-cert command is
sent, command-list MUST NOT be sent; the commands recorded in the
push certificate is used instead.
-The pack-file MUST NOT be sent if the only command used is 'delete'.
+The packfile MUST NOT be sent if the only command used is 'delete'.
-A pack-file MUST be sent if either create or update command is used,
+A packfile MUST be sent if either create or update command is used,
even if the server already has all the necessary objects. In this
-case the client MUST send an empty pack-file. The only time this
+case the client MUST send an empty packfile. The only time this
is likely to happen is if the client is creating
a new branch or a tag that points to an existing obj-id.
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
index 6d5424c..eaab6b4 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/technical/protocol-capabilities.txt
@@ -18,8 +18,9 @@ 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', 'delete-refs', 'quiet', and 'push-cert' capabilities
-are sent and recognized by the receive-pack (push to server) process.
+The 'atomic', 'report-status', 'delete-refs', 'quiet', and 'push-cert'
+capabilities are sent and recognized by the receive-pack (push to server)
The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized
by both upload-pack and receive-pack protocols. The 'agent' capability
@@ -244,6 +245,14 @@ 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).
+If the server sends the 'atomic' capability it is capable of accepting
+atomic pushes. If the pushing client requests this capability, the server
+will update the refs in one atomic transaction. Either all refs are
+updated or none.
@@ -251,6 +260,13 @@ 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.
+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.