summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/CodingGuidelines42
-rw-r--r--Documentation/RelNotes/2.3.1.txt52
-rw-r--r--Documentation/config.txt26
-rw-r--r--Documentation/diff-format.txt3
-rw-r--r--Documentation/git-p4.txt6
-rw-r--r--Documentation/git-push.txt25
-rw-r--r--Documentation/git-remote.txt20
-rw-r--r--Documentation/git-send-pack.txt7
-rw-r--r--Documentation/git.txt3
-rw-r--r--Documentation/githooks.txt30
-rw-r--r--Documentation/pretty-options.txt10
-rw-r--r--Documentation/rev-list-options.txt16
-rw-r--r--Documentation/technical/api-error-handling.txt75
-rw-r--r--Documentation/technical/api-strbuf.txt351
-rw-r--r--Documentation/technical/protocol-capabilities.txt13
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
----------------------