diff options
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/CodingGuidelines | 42 | ||||
-rw-r--r-- | Documentation/RelNotes/2.3.1.txt | 52 | ||||
-rw-r--r-- | Documentation/config.txt | 26 | ||||
-rw-r--r-- | Documentation/diff-format.txt | 3 | ||||
-rw-r--r-- | Documentation/git-p4.txt | 6 | ||||
-rw-r--r-- | Documentation/git-push.txt | 25 | ||||
-rw-r--r-- | Documentation/git-remote.txt | 20 | ||||
-rw-r--r-- | Documentation/git-send-pack.txt | 7 | ||||
-rw-r--r-- | Documentation/git.txt | 3 | ||||
-rw-r--r-- | Documentation/githooks.txt | 30 | ||||
-rw-r--r-- | Documentation/pretty-options.txt | 10 | ||||
-rw-r--r-- | Documentation/rev-list-options.txt | 16 | ||||
-rw-r--r-- | Documentation/technical/api-error-handling.txt | 75 | ||||
-rw-r--r-- | Documentation/technical/api-strbuf.txt | 351 | ||||
-rw-r--r-- | Documentation/technical/protocol-capabilities.txt | 13 |
15 files changed, 275 insertions, 404 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 894546dd75..7636199fe8 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -328,9 +328,14 @@ For C programs: - When you come up with an API, document it. - - The first #include in C files, except in platform specific - compat/ implementations, should be git-compat-util.h or another - header file that includes it, such as cache.h or builtin.h. + - The first #include in C files, except in platform specific compat/ + implementations, must be either "git-compat-util.h", "cache.h" or + "builtin.h". You do not have to include more than one of these. + + - A C file must directly include the header files that declare the + functions and the types it uses, except for the functions and types + that are made available to it by including one of the header files + it must include by the previous rule. - If you are planning a new command, consider writing it in shell or perl first, so that changes in semantics can be easily @@ -413,6 +418,29 @@ Error Messages - Say what the error is first ("cannot open %s", not "%s: cannot open") +Externally Visible Names + + - For configuration variable names, follow the existing convention: + + . The section name indicates the affected subsystem. + + . The subsection name, if any, indicates which of an unbounded set + of things to set the value for. + + . The variable name describes the effect of tweaking this knob. + + The section and variable names that consist of multiple words are + formed by concatenating the words without punctuations (e.g. `-`), + and are broken using bumpyCaps in documentation as a hint to the + reader. + + When choosing the variable namespace, do not use variable name for + specifying possibly unbounded set of things, most notably anything + an end user can freely come up with (e.g. branch names). Instead, + use subsection names or variable values, like the existing variable + branch.<name>.description does. + + Writing Documentation: Most (if not all) of the documentation pages are written in the @@ -441,6 +469,10 @@ Writing Documentation: --sort=<key> --abbrev[=<n>] + If a placeholder has multiple words, they are separated by dashes: + <new-branch-name> + --template=<template-directory> + Possibility of multiple occurrences is indicated by three dots: <file>... (One or more of <file>.) @@ -457,12 +489,12 @@ Writing Documentation: (Zero or more of <patch>. Note that the dots are inside, not outside the brackets.) - Multiple alternatives are indicated with vertical bar: + Multiple alternatives are indicated with vertical bars: [-q | --quiet] [--utf8 | --no-utf8] Parentheses are used for grouping: - [(<rev>|<range>)...] + [(<rev> | <range>)...] (Any number of either <rev> or <range>. Parens are needed to make it clear that "..." pertains to both <rev> and <range>.) diff --git a/Documentation/RelNotes/2.3.1.txt b/Documentation/RelNotes/2.3.1.txt new file mode 100644 index 0000000000..cf96186288 --- /dev/null +++ b/Documentation/RelNotes/2.3.1.txt @@ -0,0 +1,52 @@ +Git v2.3.1 Release Notes +======================== + +Fixes since v2.3 +---------------- + + * The interactive "show a list and let the user choose from it" + interface "add -i" used showed and prompted to the user even when + the candidate list was empty, against which the only "choice" the + user could have made was to choose nothing. + + * "git apply --whitespace=fix" used to under-allocate the memory + when the fix resulted in a longer text than the original patch. + + * "git log --help" used to show rev-list options that are irrelevant + to the "log" command. + + * The error message from "git commit", when a non-existing author + name was given as value to the "--author=" parameter, has been + reworded to avoid misunderstanding. + + * A broken pack .idx file in the receiving repository prevented the + dumb http transport from fetching a good copy of it from the other + side. + + * The documentation incorrectly said that C(opy) and R(ename) are the + only ones that can be followed by the score number in the output in + the --raw format. + + * Fix a misspelled conditional that is always true. + + * Code to read branch name from various files in .git/ directory + would have misbehaved if the code to write them left an empty file. + + * The "git push" documentation made the "--repo=<there>" option + easily misunderstood. + + * After attempting and failing a password-less authentication + (e.g. kerberos), libcURL refuses to fall back to password based + Basic authentication without a bit of help/encouragement. + + * Setting diff.submodule to 'log' made "git format-patch" produce + broken patches. + + * "git rerere" (invoked internally from many mergy operations) did + not correctly signal errors when told to update the working tree + files and failed to do so for whatever reason. + + * "git blame HEAD -- missing" failed to correctly say "HEAD" when it + tried to say "No such path 'missing' in HEAD". + +Also contains typofixes, documentation updates and trivial code clean-ups. diff --git a/Documentation/config.txt b/Documentation/config.txt index 04e2a71687..440784cbdd 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -683,14 +683,13 @@ core.abbrev:: for abbreviated object names to stay unique for sufficiently long time. -add.ignore-errors:: add.ignoreErrors:: +add.ignore-errors (deprecated):: Tells 'git add' to continue adding files when some files cannot be added due to indexing errors. Equivalent to the '--ignore-errors' - option of linkgit:git-add[1]. Older versions of Git accept only - `add.ignore-errors`, which does not follow the usual naming - convention for configuration variables. Newer versions of Git - honor `add.ignoreErrors` as well. + option of linkgit:git-add[1]. `add.ignore-errors` is deprecated, + as it does not follow the usual naming convention for configuration + variables. alias.*:: Command aliases for the linkgit:git[1] command wrapper - e.g. @@ -1960,7 +1959,7 @@ pack.useBitmaps:: true. You should not generally need to turn this off unless you are debugging pack bitmaps. -pack.writebitmaps:: +pack.writebitmaps (deprecated):: This is a deprecated synonym for `repack.writeBitmaps`. pack.writeBitmapHashCache:: @@ -2094,6 +2093,11 @@ rebase.autostash:: successful rebase might result in non-trivial conflicts. Defaults to false. +receive.advertiseatomic:: + By default, git-receive-pack will advertise the atomic push + capability to its clients. If you don't want to this capability + to be advertised, set this variable to false. + receive.autogc:: By default, git-receive-pack will run "git-gc --auto" after receiving data from git-push and updating refs. You can stop @@ -2153,11 +2157,15 @@ receive.denyCurrentBranch:: message. Defaults to "refuse". + Another option is "updateInstead" which will update the working -directory (must be clean) if pushing into the current branch. This option is +tree if pushing into the current branch. This option is intended for synchronizing working directories when one side is not easily accessible via interactive ssh (e.g. a live web site, hence the requirement that the working directory be clean). This mode also comes in handy when developing inside a VM to test and fix code on different Operating Systems. ++ +By default, "updateInstead" will refuse the push if the working tree or +the index have any difference from the HEAD, but the `push-to-checkout` +hook can be used to customize this. See linkgit:githooks[5]. receive.denyNonFastForwards:: If set to true, git-receive-pack will deny a ref update which is @@ -2297,7 +2305,7 @@ sendemail.smtpencryption:: See linkgit:git-send-email[1] for description. Note that this setting is not subject to the 'identity' mechanism. -sendemail.smtpssl:: +sendemail.smtpssl (deprecated):: Deprecated alias for 'sendemail.smtpencryption = ssl'. sendemail.smtpsslcertpath:: @@ -2337,7 +2345,7 @@ sendemail.validate:: sendemail.xmailer:: See linkgit:git-send-email[1] for description. -sendemail.signedoffcc:: +sendemail.signedoffcc (deprecated):: Deprecated alias for 'sendemail.signedoffbycc'. showbranch.default:: diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 15c7e794f4..85b08909ce 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -66,7 +66,8 @@ be committed) Status letters C and R are always followed by a score (denoting the percentage of similarity between the source and target of the move or -copy), and are the only ones to be so. +copy). Status letter M may be followed by a score (denoting the +percentage of dissimilarity) for file rewrites. <sha1> is shown as all 0's if a file is new on the filesystem and it is out of sync with the index. diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 6ab5f9497a..a1664b9f68 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -241,6 +241,9 @@ Git repository: Use a client spec to find the list of interesting files in p4. See the "CLIENT SPEC" section below. +-/ <path>:: + Exclude selected depot paths when cloning or syncing. + Clone options ~~~~~~~~~~~~~ These options can be used in an initial 'clone', along with the 'sync' @@ -254,9 +257,6 @@ options described above. --bare:: Perform a bare clone. See linkgit:git-clone[1]. --/ <path>:: - Exclude selected depot paths when cloning. - Submit options ~~~~~~~~~~~~~~ These options can be used to modify 'git p4 submit' behavior. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index b17283ab7a..e1a46a7958 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -9,7 +9,7 @@ git-push - Update remote refs along with associated objects SYNOPSIS -------- [verse] -'git push' [--all | --mirror | --tags] [--follow-tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] +'git push' [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>] [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream] [--signed] [--force-with-lease[=<refname>[:<expect>]]] @@ -136,6 +136,11 @@ already exists on the remote side. logged. See linkgit:git-receive-pack[1] for the details on the receiving end. +--[no-]atomic:: + Use an atomic transaction on the remote side if available. + Either all refs are updated, or on error, no refs are updated. + If the server does not support atomic pushes the push will fail. + --receive-pack=<git-receive-pack>:: --exec=<git-receive-pack>:: Path to the 'git-receive-pack' program on the remote @@ -214,22 +219,8 @@ origin +master` to force a push to the `master` branch). See the `<refspec>...` section above for details. --repo=<repository>:: - This option is only relevant if no <repository> argument is - passed in the invocation. In this case, 'git push' derives the - remote name from the current branch: If it tracks a remote - branch, then that remote repository is pushed to. Otherwise, - the name "origin" is used. For this latter case, this option - can be used to override the name "origin". In other words, - the difference between these two commands -+ --------------------------- -git push public #1 -git push --repo=public #2 --------------------------- -+ -is that #1 always pushes to "public" whereas #2 pushes to "public" -only if the current branch does not track a remote branch. This is -useful if you write an alias or script around 'git push'. + This option is equivalent to the <repository> argument. If both + are specified, the command-line argument takes precedence. -u:: --set-upstream:: diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index cb103c8b6f..a77607b852 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -130,17 +130,25 @@ branches, adds to that list. 'set-url':: -Changes URL remote points to. Sets first URL remote points to matching +Changes URLs for the remote. Sets first URL for remote <name> that matches regex <oldurl> (first URL if no <oldurl> is given) to <newurl>. If -<oldurl> doesn't match any URL, error occurs and nothing is changed. +<oldurl> doesn't match any URL, an error occurs and nothing is changed. + With '--push', push URLs are manipulated instead of fetch URLs. + -With '--add', instead of changing some URL, new URL is added. +With '--add', instead of changing existing URLs, new URL is added. + -With '--delete', instead of changing some URL, all URLs matching -regex <url> are deleted. Trying to delete all non-push URLs is an -error. +With '--delete', instead of changing existing URLs, all URLs matching +regex <url> are deleted for remote <name>. Trying to delete all +non-push URLs is an error. ++ +Note that the push URL and the fetch URL, even though they can +be set differently, must still refer to the same place. What you +pushed to the push URL should be what you would see if you +immediately fetched from the fetch URL. If you are trying to +fetch from one place (e.g. your upstream) and push to another (e.g. +your publishing repository), use two separate remotes. + 'show':: diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 2a0de42a75..45c7725dc3 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -9,7 +9,7 @@ git-send-pack - Push objects over Git protocol to another repository SYNOPSIS -------- [verse] -'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [<host>:]<directory> [<ref>...] +'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [--atomic] [<host>:]<directory> [<ref>...] DESCRIPTION ----------- @@ -62,6 +62,11 @@ be in a separate packet, and the list must end with a flush packet. Send a "thin" pack, which records objects in deltified form based on objects not included in the pack to reduce network traffic. +--atomic:: + Use an atomic transaction for updating the refs. If any of the refs + fails to update then the entire push will fail without changing any + refs. + <host>:: A remote host to house the repository. When this part is specified, 'git-receive-pack' is invoked via diff --git a/Documentation/git.txt b/Documentation/git.txt index eadbd05356..b37f1abe8c 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,10 @@ unreleased) version of Git, that is available from the 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v2.3.0/git.html[documentation for release 2.3] +* link:v2.3.1/git.html[documentation for release 2.3.1] * release notes for + link:RelNotes/2.3.1.txt[2.3.1], link:RelNotes/2.3.0.txt[2.3]. * link:v2.2.2/git.html[documentation for release 2.2.2] diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 9ef2469373..7ba0ac965d 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -341,6 +341,36 @@ Both standard output and standard error output are forwarded to 'git send-pack' on the other end, so you can simply `echo` messages for the user. +push-to-checkout +~~~~~~~~~~~~~~~~ + +This hook is invoked by 'git-receive-pack' on the remote repository, +which happens when a 'git push' is done on a local repository, when +the push tries to update the branch that is currently checked out +and the `receive.denyCurrentBranch` configuration variable is set to +`updateInstead`. Such a push by default is refused if the working +tree and the index of the remote repository has any difference from +the currently checked out commit; when both the working tree and the +index match the current commit, they are updated to match the newly +pushed tip of the branch. This hook is to be used to override the +default behaviour. + +The hook receives the commit with which the tip of the current +branch is going to be updated. It can exit with a non-zero status +to refuse the push (when it does so, it must not modify the index or +the working tree). Or it can make any necessary changes to the +working tree and to the index to bring them to the desired state +when the tip of the current branch is updated to the new commit, and +exit with a zero status. + +For example, the hook can simply run `git read-tree -u -m HEAD "$1"` +in order to emulate 'git fetch' that is run in the reverse direction +with `git push`, as the two-tree form of `read-tree -u -m` is +essentially the same as `git checkout` that switches branches while +keeping the local changes in the working tree that do not interfere +with the difference between the branches. + + pre-auto-gc ~~~~~~~~~~~ diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 8569e29d08..74aa01a0ec 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -3,9 +3,13 @@ Pretty-print the contents of the commit logs in a given format, where '<format>' can be one of 'oneline', 'short', 'medium', - 'full', 'fuller', 'email', 'raw' and 'format:<string>'. See - the "PRETTY FORMATS" section for some additional details for each - format. When omitted, the format defaults to 'medium'. + 'full', 'fuller', 'email', 'raw', 'format:<string>' + and 'tformat:<string>'. When '<format>' is none of the above, + and has '%placeholder' in it, it acts as if + '--pretty=tformat:<format>' were given. ++ +See the "PRETTY FORMATS" section for some additional details for each +format. When '=<format>' part is omitted, it defaults to 'medium'. + Note: you can specify the default pretty format in the repository configuration (see linkgit:git-config[1]). diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 2984f407a9..4ed8587c84 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -66,6 +66,10 @@ if it is part of the log message. Limit the commits output to ones that match all given `--grep`, instead of ones that match at least one. +--invert-grep:: + Limit the commits output to ones with log message that do not + match the pattern specified with `--grep=<pattern>`. + -i:: --regexp-ignore-case:: Match the regular expression limiting patterns without regard to letter @@ -172,11 +176,6 @@ explicitly. Pretend as if all objects mentioned by reflogs are listed on the command line as `<commit>`. ---indexed-objects:: - Pretend as if all trees and blobs used by the index are listed - on the command line. Note that you probably want to use - `--objects`, too. - --ignore-missing:: Upon seeing an invalid object name in the input, pretend as if the bad input was not given. @@ -644,6 +643,7 @@ Object Traversal These options are mostly targeted for packing of Git repositories. +ifdef::git-rev-list[] --objects:: Print the object IDs of any object referenced by the listed commits. `--objects foo ^bar` thus means ``send me @@ -662,9 +662,15 @@ These options are mostly targeted for packing of Git repositories. commits at the cost of increased time. This is used instead of `--objects-edge` to build ``thin'' packs for shallow repositories. +--indexed-objects:: + Pretend as if all trees and blobs used by the index are listed + on the command line. Note that you probably want to use + `--objects`, too. + --unpacked:: Only useful with `--objects`; print the object IDs that are not in packs. +endif::git-rev-list[] --no-walk[=(sorted|unsorted)]:: Only show the given commits, but do not traverse their ancestors. diff --git a/Documentation/technical/api-error-handling.txt b/Documentation/technical/api-error-handling.txt new file mode 100644 index 0000000000..fc68db126e --- /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 +kinds. + +- `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 occured, 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-strbuf.txt b/Documentation/technical/api-strbuf.txt deleted file mode 100644 index cca6543234..0000000000 --- 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()` -instead. - -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. - -Functions ---------- - -* Life cycle - -`strbuf_init`:: - - Initialize the structure. The second parameter can be zero or a bigger - number to allocate memory, in case you want to prevent further reallocs. - -`strbuf_release`:: - - 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. - -`strbuf_detach`:: - - 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. - -`strbuf_attach`:: - - 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. - -`strbuf_swap`:: - - Swap the contents of two string buffers. - -* Related to the size of the buffer - -`strbuf_avail`:: - - Determine the amount of allocated but unused memory. - -`strbuf_grow`:: - - 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. - -`strbuf_setlen`:: - - 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'. - -`strbuf_reset`:: - - Empty the buffer by setting the size of it to zero. - -* Related to the contents of the buffer - -`strbuf_trim`:: - - Strip whitespace from the beginning and end of a string. - Equivalent to performing `strbuf_rtrim()` followed by `strbuf_ltrim()`. - -`strbuf_rtrim`:: - - Strip whitespace from the end of a string. - -`strbuf_ltrim`:: - - Strip whitespace from the beginning of a string. - -`strbuf_reencode`:: - - Replace the contents of the strbuf with a reencoded form. Returns -1 - on error, 0 on success. - -`strbuf_tolower`:: - - Lowercase each character in the buffer using `tolower`. - -`strbuf_cmp`:: - - 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. - -`strbuf_addch`:: - - Add a single character to the buffer. - -`strbuf_addchars`:: - - Add a character the specified number of times to the buffer. - -`strbuf_insert`:: - - Insert data to the given position of the buffer. The remaining contents - will be shifted, not overwritten. - -`strbuf_remove`:: - - Remove given amount of data from a given position of the buffer. - -`strbuf_splice`:: - - 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. - -`strbuf_addstr`:: - -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"); ----- - -`strbuf_addbuf`:: - - Copy the contents of another buffer at the end of the current one. - -`strbuf_adddup`:: - - Copy part of the buffer from a given position till a given length to the - end of the buffer. - -`strbuf_expand`:: - - 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. - -`strbuf_expand_dict_cb`:: - - 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. - -`strbuf_addbuf_percentquote`:: - - 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. - -`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. -+ -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. - -`strbuf_read`:: - - 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. - -`strbuf_read_file`:: - - 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. - -`strbuf_readlink`:: - - 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. - -`strbuf_getline`:: - - 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`. - -`strbuf_getwholeline`:: - - Like `strbuf_getline`, but keeps the trailing terminator (if - any) in the buffer. - -`strbuf_getwholeline_fd`:: - - 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. - -`strbuf_getcwd`:: - - Set the buffer to the path of the current working directory. - -`strbuf_add_absolute_path` - - Add a path to a buffer, converting a relative path to an - absolute one in the process. Symbolic links are not - resolved. - -`stripspace`:: - - 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 - 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/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index 6d5424c1bd..4f8a7bfb4c 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) +process. 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). +atomic +------ + +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. + allow-tip-sha1-in-want ---------------------- |