summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/CodingGuidelines19
-rw-r--r--Documentation/RelNotes/2.3.3.txt39
-rw-r--r--Documentation/RelNotes/2.4.0.txt319
-rw-r--r--Documentation/config.txt47
-rw-r--r--Documentation/git-apply.txt12
-rw-r--r--Documentation/git-clean.txt8
-rw-r--r--Documentation/git-commit.txt4
-rw-r--r--Documentation/git-imap-send.txt3
-rw-r--r--Documentation/git-p4.txt6
-rw-r--r--Documentation/git-push.txt7
-rw-r--r--Documentation/git-reflog.txt144
-rw-r--r--Documentation/git-remote.txt3
-rw-r--r--Documentation/git-send-pack.txt7
-rw-r--r--Documentation/git-submodule.txt66
-rw-r--r--Documentation/git.txt3
-rw-r--r--Documentation/githooks.txt30
-rw-r--r--Documentation/gitmodules.txt21
-rw-r--r--Documentation/pretty-options.txt10
-rw-r--r--Documentation/rev-list-options.txt4
-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
22 files changed, 719 insertions, 472 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 0f8cccf52d..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
@@ -464,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>.)
@@ -480,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.3.txt b/Documentation/RelNotes/2.3.3.txt
new file mode 100644
index 0000000000..5ef12644c2
--- /dev/null
+++ b/Documentation/RelNotes/2.3.3.txt
@@ -0,0 +1,39 @@
+Git v2.3.3 Release Notes
+========================
+
+Fixes since v2.3.2
+------------------
+
+ * A corrupt input to "git diff -M" used cause us to segfault.
+
+ * The borrowed code in kwset API did not follow our usual convention
+ to use "unsigned char" to store values that range from 0-255.
+
+ * Description given by "grep -h" for its --exclude-standard option
+ was phrased poorly.
+
+ * Documentaton for "git remote add" mentioned "--tags" and
+ "--no-tags" and it was not clear that fetch from the remote in
+ the future will use the default behaviour when neither is given
+ to override it.
+
+ * "git diff --shortstat --dirstat=changes" showed a dirstat based on
+ lines that was never asked by the end user in addition to the
+ dirstat that the user asked for.
+
+ * The interaction between "git submodule update" and the
+ submodule.*.update configuration was not clearly documented.
+
+ * "git apply" was not very careful about reading from, removing,
+ updating and creating paths outside the working tree (under
+ --index/--cached) or the current directory (when used as a
+ replacement for GNU patch).
+
+ * "git daemon" looked up the hostname even when "%CH" and "%IP"
+ interpolations are not requested, which was unnecessary.
+
+ * The "interpolated-path" option of "git daemon" inserted any string
+ client declared on the "host=" capability request without checking.
+ Sanitize and limit %H and %CH to a saner and a valid DNS name.
+
+Also contains typofixes, documentation updates and trivial code clean-ups.
diff --git a/Documentation/RelNotes/2.4.0.txt b/Documentation/RelNotes/2.4.0.txt
new file mode 100644
index 0000000000..072309eaa6
--- /dev/null
+++ b/Documentation/RelNotes/2.4.0.txt
@@ -0,0 +1,319 @@
+Git 2.4 Release Notes
+=====================
+
+Updates since v2.3
+------------------
+
+Ports
+
+ * Our default I/O size (8 MiB) for large files was too large for some
+ platforms with smaller SSIZE_MAX, leading to read(2)/write(2)
+ failures.
+
+ * We did not check the curl library version before using
+ CURLOPT_PROXYAUTH feature that may not exist.
+
+
+UI, Workflows & Features
+
+ * The command usage info strings given by "git cmd -h" and in
+ documentation have been tweaked for consistency.
+
+ * The "sync" subcommand of "git p4" now allows users to exclude
+ subdirectories like its "clone" subcommand does.
+
+ * "git log --invert-grep --grep=WIP" will show only commits that do
+ not have the string "WIP" in their messages.
+
+ * "git push" has been taught a "--atomic" option that makes push to
+ update more than one ref an "all-or-none" affair.
+
+ * Extending the "push to deploy" added in 2.3, the behaviour of "git
+ push" when updating the branch that is checked out can now be
+ tweaked by push-to-checkout hook.
+
+ * Using environment variable LANGUAGE and friends on the client side,
+ HTTP-based transports now send Accept-Language when making requests.
+
+ * "git send-email" used to accept a mistaken "y" (or "yes") as an
+ answer to "What encoding do you want to use [UTF-8]? " without
+ questioning. Now it asks for confirmation when the answer looks
+ too short to be a valid encoding name.
+
+ * When "git apply --whitespace=fix" fixed whitespace errors in the
+ common context lines, the command reports that it did so.
+
+ * "git status" now allows the "-v" to be given twice to show the
+ differences that are left in the working tree not to be committed.
+
+ * "git cherry-pick" used to clean-up the log message even when it is
+ merely replaying an existing commit. It now replays the message
+ verbatim unless you are editing the message of resulting commits.
+
+ * "git archive" can now be told to set the 'text' attribute in the
+ resulting zip archive.
+
+
+Performance, Internal Implementation, Development Support etc.
+
+ * Implementation of N_() macro has been updated slightly to help us
+ detect mistakes.
+
+ * Implementation of "reflog expire" has been restructured to fit the
+ reflogs better with the recently updated ref API.
+
+ * The transport-helper did not give transport options such as
+ verbosity, progress, cloning, etc. to import and export based
+ helpers, like it did for fetch and push based helpers, robbing them
+ the chance to honor the wish of the end-users better.
+
+ * The tests that wanted to see that file becomes unreadable after
+ running "chmod a-r file", and the tests that wanted to make sure it
+ is not run as root, we used "can we write into the / directory?" as
+ a cheap substitute, but on some platforms that is not a good
+ heuristics. The tests and their prerequisites have been updated to
+ check what they really require.
+ (merge f400e51 jk/sanity later to maint).
+
+ * Various issues around "reflog expire", e.g. using --updateref when
+ expiring a reflog for a symbolic reference, have been corrected
+ and/or made saner.
+
+ * The strbuf API was explained between the API documentation and in
+ the header file. Move missing bits to strbuf.h so that programmers
+ can check only one place for all necessary information.
+
+ * The error handling functions and conventions are now documented in
+ the API manual.
+
+ * Optimize attribute look-up, mostly useful in "git grep" on a
+ project that does not use many attributes, by avoiding it when we
+ (should) know that the attributes are not defined in the first
+ place.
+
+ * Typofix in comments.
+ (merge ef2956a ak/git-pm-typofix later to maint).
+
+ * Code clean-up.
+ (merge 0b868f0 sb/hex-object-name-is-at-most-41-bytes-long later to maint).
+ (merge 5d30851 dp/remove-duplicated-header-inclusion later to maint).
+
+ * Simplify the ref transaction API around how "the ref should be
+ pointing at this object" is specified.
+
+
+Also contains various documentation updates and code clean-ups.
+
+
+Fixes since v2.3
+----------------
+
+Unless otherwise noted, all the fixes since v2.3 in the maintenance
+track are contained in this release (see the maintenance releases'
+notes for details).
+
+ * "git blame HEAD -- missing" failed to correctly say "HEAD" when it
+ tried to say "No such path 'missing' in HEAD".
+ (merge a46442f jk/blame-commit-label later to maint).
+
+ * "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.
+ (merge 89ea903 jn/rerere-fail-on-auto-update-failure later to maint).
+
+ * Setting diff.submodule to 'log' made "git format-patch" produce
+ broken patches.
+ (merge 339de50 dk/format-patch-ignore-diff-submodule later to maint).
+
+ * 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.
+ (merge 4dbe664 bc/http-fallback-to-password-after-krb-fails later to maint).
+
+ * The "git push" documentation made the "--repo=<there>" option
+ easily misunderstood.
+ (merge 57b92a7 mg/push-repo-option-doc later to maint).
+
+ * Code to read branch name from various files in .git/ directory
+ would have misbehaved if the code to write them left an empty file.
+ (merge 66ec904 jk/status-read-branch-name-fix later to maint).
+
+ * A misspelled conditional that is always true has been fixed.
+ (merge 94ee8e2 jk/remote-curl-an-array-in-struct-cannot-be-null later to maint).
+
+ * 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.
+ (merge ac1c2d9 jc/diff-format-doc later to maint).
+
+ * 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.
+ (merge 8b9c2dd jk/dumb-http-idx-fetch-fix later to maint).
+
+ * 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.
+ (merge 1044b1f mg/commit-author-no-match-malformed-message later to maint).
+
+ * "git log --help" used to show rev-list options that are irrelevant
+ to the "log" command.
+ (merge 3cab02d jc/doc-log-rev-list-options later to maint).
+
+ * "git apply --whitespace=fix" used to under-allocate the memory when
+ the fix resulted in a longer text than the original patch.
+ (merge 407a792 jc/apply-ws-fix-expands later to maint).
+
+ * 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.
+ (merge a9c4641 ak/add-i-empty-candidates later to maint).
+
+ * The insn sheet "git rebase -i" creates did not fully honor
+ core.abbrev settings.
+ (merge edb72d5 ks/rebase-i-abbrev later to maint).
+
+ * "git fetch" over a remote-helper that cannot respond to "list"
+ command could not fetch from a symbolic reference e.g. HEAD.
+ (merge 33cae54 mh/deref-symref-over-helper-transport later to maint).
+
+ * "git push --signed" gave an incorrectly worded error message when
+ the other side did not support the capability.
+ (merge 45917f0 jc/push-cert later to maint).
+
+ * We didn't format an integer that wouldn't fit in "int" but in
+ "uintmax_t" correctly.
+ (merge d306f3d jk/decimal-width-for-uintmax later to maint).
+
+ * Reading configuration from a blob object, when it ends with a lone
+ CR, use to confuse the configuration parser.
+ (merge 1d0655c jk/config-no-ungetc-eof later to maint).
+
+ * The pack bitmap support did not build with older versions of GCC.
+ (merge bd4e882 jk/pack-bitmap later to maint).
+
+ * The documentation wasn't clear that "remote.<nick>.pushURL" and
+ "remote.<nick>.URL" are there to name the same repository accessed
+ via different transports, not two separate repositories.
+ (merge 697f652 jc/remote-set-url-doc later to maint).
+
+ * Older GnuPG implementations may not correctly import the keyring
+ material we prepare for the tests to use.
+ (merge 1f985d6 ch/new-gpg-drops-rfc-1991 later to maint).
+
+ * The credential helper for Windows (in contrib/) used to mishandle
+ a user name with an at-sign in it.
+ (merge 13d261e av/wincred-with-at-in-username-fix later to maint).
+
+ * Longstanding configuration variable naming rules has been added to
+ the documentation.
+ (merge 35840a3 jc/conf-var-doc later to maint).
+
+ * An earlier workaround to squelch unhelpful deprecation warnings
+ from the complier on Mac OSX unnecessarily set minimum required
+ version of the OS, which the user might want to raise (or lower)
+ for other reasons.
+ (merge 88c03eb es/squelch-openssl-warnings-on-macosx later to maint).
+
+ * Certain older vintages of cURL give irregular output from
+ "curl-config --vernum", which confused our build system.
+ (merge 3af6792 tc/curl-vernum-output-broken-in-7.11 later to maint).
+
+ * In v2.2.0, we broke "git prune" that runs in a repository that
+ borrows from an alternate object store.
+ (merge b0a4264 jk/prune-mtime later to maint).
+
+ * "git submodule add" failed to squash "path/to/././submodule" to
+ "path/to/submodule".
+ (merge 8196e72 ps/submodule-sanitize-path-upon-add later to maint).
+
+ * "git merge-file" did not work correctly in a subdirectory.
+ (merge 204a8ff ab/merge-file-prefix later to maint).
+
+ * "git blame" died, trying to free an uninitialized piece of memory.
+ (merge e600592 es/blame-commit-info-fix later to maint).
+
+ * "git fast-import" used to crash when it could not close and
+ conclude the resulting packfile cleanly.
+ (merge 5e915f3 jk/fast-import-die-nicely-fix later to maint).
+
+ * "update-index --refresh" used to leak when an entry cannot be
+ refreshed for whatever reason.
+ (merge bc1c2ca sb/plug-leak-in-make-cache-entry later to maint).
+
+ * The "interpolated-path" option of "git daemon" inserted any string
+ client declared on the "host=" capability request without checking.
+ Sanitize and limit %H and %CH to a saner and a valid DNS name.
+ (merge b485373 jk/daemon-interpolate later to maint).
+
+ * "git daemon" looked up the hostname even when "%CH" and "%IP"
+ interpolations are not requested, which was unnecessary.
+ (merge dc8edc8 rs/daemon-interpolate later to maint).
+
+ * Even though we officially haven't dropped Perl 5.8 support, the
+ Getopt::Long package that came with it does not support "--no-"
+ prefix to negate a boolean option; manually add support to help
+ people with older Getopt::Long package.
+ (merge f471494 km/send-email-getopt-long-workarounds later to maint).
+
+ * "git apply" was not very careful about reading from, removing,
+ updating and creating paths outside the working tree (under
+ --index/--cached) or the current directory (when used as a
+ replacement for GNU patch).
+ (merge e0d201b jc/apply-beyond-symlink later to maint).
+
+ * A breakage to git-svn around v2.2 era that triggers premature
+ closing of FileHandle has been corrected.
+ (merge e426311 ew/svn-maint-fixes later to maint).
+
+ * We did not parse username followed by literal IPv6 address in SSH
+ transport URLs, e.g. ssh://user@[2001:db8::1]:22/repo.git
+ correctly.
+ (merge 3f55cca tb/connect-ipv6-parse-fix later to maint).
+
+ * The configuration variable 'mailinfo.scissors' was hard to
+ discover in the documentation.
+ (merge afb5de7 mm/am-c-doc later to maint).
+
+ * The interaction between "git submodule update" and the
+ submodule.*.update configuration was not clearly documented.
+ (merge 5c31acf ms/submodule-update-config-doc later to maint).
+
+ * "git diff --shortstat --dirstat=changes" showed a dirstat based on
+ lines that was never asked by the end user in addition to the
+ dirstat that the user asked for.
+ (merge ab27389 mk/diff-shortstat-dirstat-fix later to maint).
+
+ * "git remote add" mentioned "--tags" and "--no-tags" and was not
+ clear that fetch from the remote in the future will use the default
+ behaviour when neither is given to override it.
+ (merge aaba0ab mg/doc-remote-tags-or-not later to maint).
+
+ * Description given by "grep -h" for its --exclude-standard option
+ was phrased poorly.
+ (merge 77fdb8a nd/grep-exclude-standard-help-fix later to maint).
+
+ * "git rebase -i" recently started to include the number of
+ commits in the insn sheet to be processed, but on a platform
+ that prepends leading whitespaces to "wc -l" output, the numbers
+ are shown with extra whitespaces that aren't necessary.
+ (merge 2185d3b es/rebase-i-count-todo later to maint).
+
+ * The borrowed code in kwset API did not follow our usual convention
+ to use "unsigned char" to store values that range from 0-255.
+ (merge 189c860 bw/kwset-use-unsigned later to maint).
+
+ * A corrupt input to "git diff -M" used to cause it to segfault.
+ (merge 4d6be03 jk/diffcore-rename-duplicate later to maint).
+
+ * Code cleanups and documentaiton updates.
+ (merge 2ce63e9 rs/simple-cleanups later to maint).
+ (merge 33baa69 rj/no-xopen-source-for-cygwin later to maint).
+ (merge 817d03e jc/diff-test-updates later to maint).
+ (merge eb32c66 ak/t5516-typofix later to maint).
+ (merge bcd57cb mr/doc-clean-f-f later to maint).
+ (merge 0d6accc mg/doc-status-color-slot later to maint).
+ (merge 53e53c7 sg/completion-remote later to maint).
+ (merge 8fa7975 ak/git-done-help-cleanup later to maint).
+ (merge 9a6f128 rs/deflate-init-cleanup later to maint).
diff --git a/Documentation/config.txt b/Documentation/config.txt
index e18f712a13..5666d27b4a 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -154,9 +154,8 @@ color::
`white`; the attributes are `bold`, `dim`, `ul`, `blink` and
`reverse`. The first color given is the foreground; the
second is the background. The position of the attribute, if
- any, doesn't matter. Attributes may be turned off
- specifically by prefixing them with `no` (e.g., `noreverse`,
- `noul`, etc).
+ any, doesn't matter. Attributes may be turned off specifically
+ by prefixing them with `no` (e.g., `noreverse`, `noul`, etc).
+
Colors (foreground and background) may also be given as numbers between
0 and 255; these use ANSI 256-color mode (but note that not all
@@ -983,9 +982,10 @@ color.status.<slot>::
`added` or `updated` (files which are added but not committed),
`changed` (files which are changed but not added in the index),
`untracked` (files which are not tracked by Git),
- `branch` (the current branch), or
+ `branch` (the current branch),
`nobranch` (the color the 'no branch' warning is shown in, defaulting
- to red).
+ to red), or
+ `unmerged` (files which have unmerged changes).
color.ui::
This variable determines the default value for variables such
@@ -2126,6 +2126,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
@@ -2185,11 +2190,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
@@ -2434,12 +2443,16 @@ status.submodulesummary::
submodule.<name>.path::
submodule.<name>.url::
+ The path within this project and URL for a submodule. These
+ variables are initially populated by 'git submodule init'. See
+ linkgit:git-submodule[1] and linkgit:gitmodules[5] for
+ details.
+
submodule.<name>.update::
- The path within this project, URL, and the updating strategy
- for a submodule. These variables are initially populated
- by 'git submodule init'; edit them to override the
- URL and other values found in the `.gitmodules` file. See
- linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.
+ The default update procedure for a submodule. This variable
+ is populated by `git submodule init` from the
+ linkgit:gitmodules[5] file. See description of 'update'
+ command in linkgit:git-submodule[1].
submodule.<name>.branch::
The remote branch name for a submodule, used by `git submodule
@@ -2571,6 +2584,18 @@ user.signingkey::
This option is passed unchanged to gpg's --local-user parameter,
so you may specify a key using any method that gpg supports.
+versionsort.prereleaseSuffix::
+ When version sort is used in linkgit:git-tag[1], prerelease
+ tags (e.g. "1.0-rc1") may appear after the main release
+ "1.0". By specifying the suffix "-rc" in this variable,
+ "1.0-rc1" will appear before "1.0".
++
+This variable can be specified multiple times, once per suffix. The
+order of suffixes in the config file determines the sorting order
+(e.g. if "-pre" appears before "-rc" in the config file then 1.0-preXX
+is sorted before 1.0-rcXX). The sorting order between different
+suffixes is undefined if they are in multiple config files.
+
web.browser::
Specify a web browser that may be used by some commands.
Currently only linkgit:git-instaweb[1] and linkgit:git-help[1]
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index f605327946..9489664cfa 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -16,7 +16,7 @@ SYNOPSIS
[--ignore-space-change | --ignore-whitespace ]
[--whitespace=(nowarn|warn|fix|error|error-all)]
[--exclude=<path>] [--include=<path>] [--directory=<root>]
- [--verbose] [<patch>...]
+ [--verbose] [--unsafe-paths] [<patch>...]
DESCRIPTION
-----------
@@ -229,6 +229,16 @@ For example, a patch that talks about updating `a/git-gui.sh` to `b/git-gui.sh`
can be applied to the file in the working tree `modules/git-gui/git-gui.sh` by
running `git apply --directory=modules/git-gui`.
+--unsafe-paths::
+ By default, a patch that affects outside the working area
+ (either a Git controlled working tree, or the current working
+ directory when "git apply" is used as a replacement of GNU
+ patch) is rejected as a mistake (or a mischief).
++
+When `git apply` is used as a "better GNU patch", the user can pass
+the `--unsafe-paths` option to override this safety check. This option
+has no effect when `--index` or `--cached` is in use.
+
Configuration
-------------
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 94b6d19cf2..641681f61a 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -34,8 +34,12 @@ OPTIONS
-f::
--force::
If the Git configuration variable clean.requireForce is not set
- to false, 'git clean' will refuse to run unless given -f, -n or
- -i.
+ to false, 'git clean' will refuse to delete files or directories
+ unless given -f, -n or -i. Git will refuse to delete directories
+ with .git sub directory or file unless a second -f
+ is given. This affects also git submodules where the storage area
+ of the removed submodule under .git/modules/ is not removed until
+ -f is given twice.
-i::
--interactive::
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 1e74b75d38..f14d2ececd 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -284,6 +284,10 @@ configuration variable documented in linkgit:git-config[1].
would be committed at the bottom of the commit message
template. Note that this diff output doesn't have its
lines prefixed with '#'.
++
+If specified twice, show in addition the unified diff between
+what would be committed and the worktree files, i.e. the unstaged
+changes to tracked files.
-q::
--quiet::
diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 77aacf1309..5d1e4c80cd 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -44,7 +44,8 @@ OPTIONS
--no-curl::
Talk to the IMAP server using git's own IMAP routines instead of
- using libcurl.
+ using libcurl. Ignored if Git was built with the NO_OPENSSL option
+ set.
CONFIGURATION
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 58cc59f20c..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
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index 70791b9fd8..5e7908e4f7 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -17,85 +17,113 @@ The command takes various subcommands, and different options
depending on the subcommand:
[verse]
-'git reflog expire' [--dry-run] [--stale-fix] [--verbose]
- [--expire=<time>] [--expire-unreachable=<time>] [--all] <refs>...
-'git reflog delete' ref@\{specifier\}...
'git reflog' ['show'] [log-options] [<ref>]
+'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
+ [--rewrite] [--updateref] [--stale-fix]
+ [--dry-run] [--verbose] [--all | <refs>...]
+'git reflog delete' [--rewrite] [--updateref]
+ [--dry-run] [--verbose] ref@\{specifier\}...
+
+Reference logs, or "reflogs", record when the tips of branches and
+other references were updated in the local repository. Reflogs are
+useful in various Git commands, to specify the old value of a
+reference. For example, `HEAD@{2}` means "where HEAD used to be two
+moves ago", `master@{one.week.ago}` means "where master used to point
+to one week ago in this local repository", and so on. See
+linkgit:gitrevisions[7] for more details.
+
+This command manages the information recorded in the reflogs.
+
+The "show" subcommand (which is also the default, in the absence of
+any subcommands) shows the log of the reference provided in the
+command-line (or `HEAD`, by default). The reflog covers all recent
+actions, and in addition the `HEAD` reflog records branch switching.
+`git reflog show` is an alias for `git log -g --abbrev-commit
+--pretty=oneline`; see linkgit:git-log[1] for more information.
+
+The "expire" subcommand prunes older reflog entries. Entries older
+than `expire` time, or entries older than `expire-unreachable` time
+and not reachable from the current tip, are removed from the reflog.
+This is typically not used directly by end users -- instead, see
+linkgit:git-gc[1].
+
+The "delete" subcommand deletes single entries from the reflog. Its
+argument must be an _exact_ entry (e.g. "`git reflog delete
+master@{2}`"). This subcommand is also typically not used directly by
+end users.
-Reflog is a mechanism to record when the tip of branches are
-updated. This command is to manage the information recorded in it.
-The subcommand "expire" is used to prune older reflog entries.
-Entries older than `expire` time, or entries older than
-`expire-unreachable` time and not reachable from the current
-tip, are removed from the reflog. This is typically not used
-directly by the end users -- instead, see linkgit:git-gc[1].
-
-The subcommand "show" (which is also the default, in the absence of any
-subcommands) will take all the normal log options, and show the log of
-the reference provided in the command-line (or `HEAD`, by default).
-The reflog will cover all recent actions (HEAD reflog records branch switching
-as well). It is an alias for `git log -g --abbrev-commit --pretty=oneline`;
-see linkgit:git-log[1].
+OPTIONS
+-------
-The reflog is useful in various Git commands, to specify the old value
-of a reference. For example, `HEAD@{2}` means "where HEAD used to be
-two moves ago", `master@{one.week.ago}` means "where master used to
-point to one week ago", and so on. See linkgit:gitrevisions[7] for
-more details.
+Options for `show`
+~~~~~~~~~~~~~~~~~~
-To delete single entries from the reflog, use the subcommand "delete"
-and specify the _exact_ entry (e.g. "`git reflog delete master@{2}`").
+`git reflog show` accepts any of the options accepted by `git log`.
-OPTIONS
--------
+Options for `expire`
+~~~~~~~~~~~~~~~~~~~~
---stale-fix::
- This revamps the logic -- the definition of "broken commit"
- becomes: a commit that is not reachable from any of the refs and
- there is a missing object among the commit, tree, or blob
- objects reachable from it that is not reachable from any of the
- refs.
-+
-This computation involves traversing all the reachable objects, i.e. it
-has the same cost as 'git prune'. Fortunately, once this is run, we
-should not have to ever worry about missing objects, because the current
-prune and pack-objects know about reflogs and protect objects referred by
-them.
+--all::
+ Process the reflogs of all references.
--expire=<time>::
- Entries older than this time are pruned. Without the
- option it is taken from configuration `gc.reflogExpire`,
- which in turn defaults to 90 days. --expire=all prunes
- entries regardless of their age; --expire=never turns off
- pruning of reachable entries (but see --expire-unreachable).
+ Prune entries older than the specified time. If this option is
+ not specified, the expiration time is taken from the
+ configuration setting `gc.reflogExpire`, which in turn
+ defaults to 90 days. `--expire=all` prunes entries regardless
+ of their age; `--expire=never` turns off pruning of reachable
+ entries (but see `--expire-unreachable`).
--expire-unreachable=<time>::
- Entries older than this time and not reachable from
- the current tip of the branch are pruned. Without the
- option it is taken from configuration
- `gc.reflogExpireUnreachable`, which in turn defaults to
- 30 days. --expire-unreachable=all prunes unreachable
- entries regardless of their age; --expire-unreachable=never
+ Prune entries older than `<time>` that are not reachable from
+ the current tip of the branch. If this option is not
+ specified, the expiration time is taken from the configuration
+ setting `gc.reflogExpireUnreachable`, which in turn defaults
+ to 30 days. `--expire-unreachable=all` prunes unreachable
+ entries regardless of their age; `--expire-unreachable=never`
turns off early pruning of unreachable entries (but see
- --expire).
-
---all::
- Instead of listing <refs> explicitly, prune all refs.
+ `--expire`).
--updateref::
- Update the ref with the sha1 of the top reflog entry (i.e.
- <ref>@\{0\}) after expiring or deleting.
+ Update the reference to the value of the top reflog entry (i.e.
+ <ref>@\{0\}) if the previous top entry was pruned. (This
+ option is ignored for symbolic references.)
--rewrite::
- While expiring or deleting, adjust each reflog entry to ensure
- that the `old` sha1 field points to the `new` sha1 field of the
- previous entry.
+ If a reflog entry's predecessor is pruned, adjust its "old"
+ SHA-1 to be equal to the "new" SHA-1 field of the entry that
+ now precedes it.
+
+--stale-fix::
+ Prune any reflog entries that point to "broken commits". A
+ broken commit is a commit that is not reachable from any of
+ the reference tips and that refers, directly or indirectly, to
+ a missing commit, tree, or blob object.
++
+This computation involves traversing all the reachable objects, i.e. it
+has the same cost as 'git prune'. It is primarily intended to fix
+corruption caused by garbage collecting using older versions of Git,
+which didn't protect objects referred to by reflogs.
+
+-n::
+--dry-run::
+ Do not actually prune any entries; just show what would have
+ been pruned.
--verbose::
Print extra information on screen.
+
+Options for `delete`
+~~~~~~~~~~~~~~~~~~~~
+
+`git reflog delete` accepts options `--updateref`, `--rewrite`, `-n`,
+`--dry-run`, and `--verbose`, with the same meanings as when they are
+used with `expire`.
+
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index a77607b852..4c6d6de7b7 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -58,6 +58,9 @@ remote repository.
With `--no-tags` option, `git fetch <name>` does not import tags from
the remote repository.
+
+By default, only tags on fetched branches are imported
+(see linkgit:git-fetch[1]).
++
With `-t <branch>` option, instead of the default glob
refspec for the remote to track all branches under
the `refs/remotes/<name>/` namespace, a refspec to track only `<branch>`
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-submodule.txt b/Documentation/git-submodule.txt
index 8e6af65da0..2c25916f8f 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -154,27 +154,51 @@ If `--force` is specified, the submodule's work tree will be removed even if
it contains local modifications.
update::
- Update the registered submodules, i.e. clone missing submodules and
- checkout the commit specified in the index of the containing repository.
- This will make the submodules HEAD be detached unless `--rebase` or
- `--merge` is specified or the key `submodule.$name.update` is set to
- `rebase`, `merge` or `none`. `none` can be overridden by specifying
- `--checkout`. Setting the key `submodule.$name.update` to `!command`
- will cause `command` to be run. `command` can be any arbitrary shell
- command that takes a single argument, namely the sha1 to update to.
+
+--
+Update the registered submodules to match what the superproject
+expects by cloning missing submodules and updating the working tree of
+the submodules. The "updating" can be done in several ways depending
+on command line options and the value of `submodule.<name>.update`
+configuration variable. Supported update procedures are:
+
+ checkout;; the commit recorded in the superproject will be
+ checked out in the submodule on a detached HEAD. This is
+ done when `--checkout` option is given, or no option is
+ given, and `submodule.<name>.update` is unset, or if it is
+ set to 'checkout'.
++
+If `--force` is specified, the submodule will be checked out (using
+`git checkout --force` if appropriate), even if the commit specified
+in the index of the containing repository already matches the commit
+checked out in the submodule.
+
+ rebase;; the current branch of the submodule will be rebased
+ onto the commit recorded in the superproject. This is done
+ when `--rebase` option is given, or no option is given, and
+ `submodule.<name>.update` is set to 'rebase'.
+
+ merge;; the commit recorded in the superproject will be merged
+ into the current branch in the submodule. This is done
+ when `--merge` option is given, or no option is given, and
+ `submodule.<name>.update` is set to 'merge'.
+
+ custom command;; arbitrary shell command that takes a single
+ argument (the sha1 of the commit recorded in the
+ superproject) is executed. This is done when no option is
+ given, and `submodule.<name>.update` has the form of
+ '!command'.
+
+When no option is given and `submodule.<name>.update` is set to 'none',
+the submodule is not updated.
+
If the submodule is not yet initialized, and you just want to use the
setting as stored in .gitmodules, you can automatically initialize the
submodule with the `--init` option.
-+
+
If `--recursive` is specified, this command will recurse into the
registered submodules, and update any nested submodules within.
-+
-If `--force` is specified, the submodule will be checked out (using
-`git checkout --force` if appropriate), even if the commit specified in the
-index of the containing repository already matches the commit checked out in
-the submodule.
-
+--
summary::
Show commit summary between the given commit (defaults to HEAD) and
working tree/index. For a submodule in question, a series of commits
@@ -238,10 +262,12 @@ OPTIONS
When running add, allow adding an otherwise ignored submodule path.
When running deinit the submodule work trees will be removed even if
they contain local changes.
- When running update, throw away local changes in submodules when
- switching to a different commit; and always run a checkout operation
- in the submodule, even if the commit listed in the index of the
- containing repository matches the commit checked out in the submodule.
+ When running update (only effective with the checkout procedure),
+ throw away local changes in submodules when switching to a
+ different commit; and always run a checkout operation in the
+ submodule, even if the commit listed in the index of the
+ containing repository matches the commit checked out in the
+ submodule.
--cached::
This option is only valid for status and summary commands. These
@@ -302,7 +328,7 @@ the submodule itself.
Checkout the commit recorded in the superproject on a detached HEAD
in the submodule. This is the default behavior, the main use of
this option is to override `submodule.$name.update` when set to
- `merge`, `rebase` or `none`.
+ a value other than `checkout`.
If the key `submodule.$name.update` is either not explicitly set or
set to `checkout`, this option is implicit.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 52c4d2a7c9..af306209e9 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.2/git.html[documentation for release 2.3.2]
+* link:v2.3.3/git.html[documentation for release 2.3.3]
* release notes for
+ link:RelNotes/2.3.3.txt[2.3.3],
link:RelNotes/2.3.2.txt[2.3.2],
link:RelNotes/2.3.1.txt[2.3.1],
link:RelNotes/2.3.0.txt[2.3].
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/gitmodules.txt b/Documentation/gitmodules.txt
index f6c0dfd029..ac70eca321 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -38,18 +38,15 @@ submodule.<name>.url::
In addition, there are a number of optional keys:
submodule.<name>.update::
- Defines what to do when the submodule is updated by the superproject.
- If 'checkout' (the default), the new commit specified in the
- superproject will be checked out in the submodule on a detached HEAD.
- If 'rebase', the current branch of the submodule will be rebased onto
- the commit specified in the superproject. If 'merge', the commit
- specified in the superproject will be merged into the current branch
- in the submodule.
- If 'none', the submodule with name `$name` will not be updated
- by default.
-
- This config option is overridden if 'git submodule update' is given
- the '--merge', '--rebase' or '--checkout' options.
+ Defines the default update procedure for the named submodule,
+ i.e. how the submodule is updated by "git submodule update"
+ command in the superproject. This is only used by `git
+ submodule init` to initialize the configuration variable of
+ the same name. Allowed values here are 'checkout', 'rebase',
+ 'merge' or 'none'. See description of 'update' command in
+ linkgit:git-submodule[1] for their meaning. Note that the
+ '!command' form is intentionally ignored here for security
+ reasons.
submodule.<name>.branch::
A remote branch name for tracking updates in the upstream submodule.
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 97ef2e8e71..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
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
----------------------