summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/RelNotes/2.2.0.txt132
-rw-r--r--Documentation/config.txt3
-rw-r--r--Documentation/git-fast-export.txt61
-rw-r--r--Documentation/git-imap-send.txt10
-rw-r--r--Documentation/git-init.txt85
-rw-r--r--Documentation/git-rebase.txt7
-rw-r--r--Documentation/git-rev-list.txt2
-rw-r--r--Documentation/git-send-pack.txt13
-rw-r--r--Documentation/git-svn.txt17
-rw-r--r--Documentation/git-update-index.txt2
-rw-r--r--Documentation/git.txt5
-rw-r--r--Documentation/gitattributes.txt4
-rw-r--r--Documentation/pretty-formats.txt8
-rw-r--r--Documentation/rev-list-options.txt13
-rw-r--r--Documentation/technical/api-config.txt155
-rw-r--r--Documentation/technical/api-run-command.txt8
-rw-r--r--Documentation/technical/api-strbuf.txt14
-rw-r--r--Documentation/technical/pack-protocol.txt2
18 files changed, 463 insertions, 78 deletions
diff --git a/Documentation/RelNotes/2.2.0.txt b/Documentation/RelNotes/2.2.0.txt
new file mode 100644
index 0000000000..22b73618fc
--- /dev/null
+++ b/Documentation/RelNotes/2.2.0.txt
@@ -0,0 +1,132 @@
+Git v2.2 Release Notes
+======================
+
+Updates since v2.1
+------------------
+
+Ports
+
+ * Building on older MacOS X systems automatically sets
+ the necessary NO_APPLE_COMMON_CRYPTO build-time option.
+
+
+UI, Workflows & Features
+
+ * "git config --edit --global" starts from a skeletal per-user
+ configuration file contents, instead of a total blank, when the
+ user does not already have any. This immediately reduces the
+ need for a later "Have you forgotten setting core.user?" and we
+ can add more to the template as we gain more experience.
+
+ * "git stash list -p" used to be almost always a no-op because each
+ stash entry is represented as a merge commit. It learned to show
+ the difference between the base commit version and the working tree
+ version, which is in line with what "git show" gives.
+
+Performance, Internal Implementation, etc.
+
+ * The API to manipulate the "refs" is currently undergoing a revamp
+ to make it more transactional, with the eventual goal to allow
+ all-or-none atomic updates and migrating the storage to something
+ other than the traditional filesystem based one (e.g. databases).
+
+ * We no longer attempt to keep track of individual dependencies to
+ the header files in the build procedure, relying on automated
+ dependency generation support from modern compilers.
+
+ * In tests, we have been using NOT_{MINGW,CYGWIN} test prerequisites
+ long before negated prerequisites e.g. !MINGW were invented.
+ The former has been converted to the latter to avoid confusion.
+
+ * Looking up remotes configuration in a repository with very many
+ remotes defined has been optimized.
+
+ * There are cases where you lock and open to write a file, close it
+ to show the updated contents to external processes, and then have
+ to update the file again while still holding the lock, but the
+ lockfile API lacked support for such an access pattern.
+
+ * The API to allocate the structure to keep track of commit
+ decoration has been updated to make it less cumbersome to use.
+
+ * An in-core caching layer to let us avoid reading the same
+ configuration files number of times has been added. A few commands
+ have been converted to use this subsystem.
+
+ * Various code paths have been cleaned up and simplified by using
+ "strbuf", "starts_with()", and "skip_prefix()" APIs more.
+
+ * A few codepaths that died when large blobs that would not fit in
+ core are involved in their operation have been taught to punt
+ instead, by e.g. marking too large a blob as not to be diffed.
+
+ * A few more code paths in "commit" and "checkout" have been taught
+ to repopulate the cache-tree in the index, to help speed up later
+ "write-tree" (used in "commit") and "diff-index --cached" (used in
+ "status").
+
+
+Also contains various documentation updates and code clean-ups.
+
+
+Fixes since v2.1
+----------------
+
+Unless otherwise noted, all the fixes since v2.1 in the maintenance
+track are contained in this release (see the maintenance releases'
+notes for details).
+
+ * "git log --pretty/format=" with an empty format string did not
+ mean the more obvious "No output whatsoever" but "Use default
+ format", which was counterintuitive.
+ (merge b9c7d6e jk/pretty-empty-format later to maint).
+
+ * Implementations of "tar" that do not understand an extended pax
+ header would extract the contents of it in a regular file; make
+ sure the permission bits of this file follows the same tar.umask
+ configuration setting.
+
+ * "git -c section.var command" and "git -c section.var= command"
+ should pass the configuration differently (the former should be a
+ boolean true, the latter should be an empty string).
+ (merge a789ca7 jk/command-line-config-empty-string later to maint).
+
+ * Applying a patch not generated by Git in a subdirectory used to
+ check the whitespace breakage using the attributes for incorrect
+ paths. Also whitespace checks were performed even for paths
+ excluded via "git apply --exclude=<path>" mechanism.
+ (merge 477a08a jc/apply-ws-prefix later to maint).
+
+ * "git bundle create" with date-range specification were meant to
+ exclude tags outside the range, but it didn't.
+ (merge 2c8544a lf/bundle-exclusion later to maint).
+
+ * "git add x" where x that used to be a directory has become a
+ symbolic link to a directory misbehaved.
+ (merge ccad42d rs/refresh-beyond-symlink later to maint).
+
+ * The prompt script checked $GIT_DIR/ref/stash file to see if there
+ is a stash, which was a no-no.
+ (merge 0fa7f01 jk/prompt-stash-could-be-packed later to maint).
+
+ * Pack-protocol documentation had a minor typo.
+ (merge 5d146f7 sp/pack-protocol-doc-on-shallow later to maint).
+
+ * "git checkout -m" did not switch to another branch while carrying
+ the local changes forward when a path was deleted from the index.
+ (merge 6a143aa jn/unpack-trees-checkout-m-carry-deletion later to maint).
+
+ * With sufficiently long refnames, "git fast-import" could have
+ overflown an on-stack buffer.
+ (merge c252785 jk/fast-import-fixes later to maint).
+
+ * After "pack-refs --prune" packed refs at the top-level, it failed
+ to prune them.
+ (merge afd11d3 jk/prune-top-level-refs-after-packing later to maint).
+
+ * Progress output from "git gc --auto" was visible in "git fetch -q".
+ (merge 6fceed3 nd/fetch-pass-quiet-to-gc-child-process later to maint).
+
+ * We used to pass -1000 to poll(2), expecting it to also mean "no
+ timeout", which should be spelled as -1.
+ (merge 6c71f8b et/spell-poll-infinite-with-minus-one-only later to maint).
diff --git a/Documentation/config.txt b/Documentation/config.txt
index c55c22ab7b..3b5b24aeb7 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -499,7 +499,8 @@ core.bigFileThreshold::
Files larger than this size are stored deflated, without
attempting delta compression. Storing large files without
delta compression avoids excessive memory usage, at the
- slight expense of increased disk usage.
+ slight expense of increased disk usage. Additionally files
+ larger than this size are always treated as binary.
+
Default is 512 MiB on all platforms. This should be reasonable
for most projects as source code and other text files can still
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index 221506b04b..dbe9a46833 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -105,6 +105,11 @@ marks the same across runs.
in the commit (as opposed to just listing the files which are
different from the commit's first parent).
+--anonymize::
+ Anonymize the contents of the repository while still retaining
+ the shape of the history and stored tree. See the section on
+ `ANONYMIZING` below.
+
--refspec::
Apply the specified refspec to each ref exported. Multiple of them can
be specified.
@@ -141,6 +146,62 @@ referenced by that revision range contains the string
'refs/heads/master'.
+ANONYMIZING
+-----------
+
+If the `--anonymize` option is given, git will attempt to remove all
+identifying information from the repository while still retaining enough
+of the original tree and history patterns to reproduce some bugs. The
+goal is that a git bug which is found on a private repository will
+persist in the anonymized repository, and the latter can be shared with
+git developers to help solve the bug.
+
+With this option, git will replace all refnames, paths, blob contents,
+commit and tag messages, names, and email addresses in the output with
+anonymized data. Two instances of the same string will be replaced
+equivalently (e.g., two commits with the same author will have the same
+anonymized author in the output, but bear no resemblance to the original
+author string). The relationship between commits, branches, and tags is
+retained, as well as the commit timestamps (but the commit messages and
+refnames bear no resemblance to the originals). The relative makeup of
+the tree is retained (e.g., if you have a root tree with 10 files and 3
+trees, so will the output), but their names and the contents of the
+files will be replaced.
+
+If you think you have found a git bug, you can start by exporting an
+anonymized stream of the whole repository:
+
+---------------------------------------------------
+$ git fast-export --anonymize --all >anon-stream
+---------------------------------------------------
+
+Then confirm that the bug persists in a repository created from that
+stream (many bugs will not, as they really do depend on the exact
+repository contents):
+
+---------------------------------------------------
+$ git init anon-repo
+$ cd anon-repo
+$ git fast-import <../anon-stream
+$ ... test your bug ...
+---------------------------------------------------
+
+If the anonymized repository shows the bug, it may be worth sharing
+`anon-stream` along with a regular bug report. Note that the anonymized
+stream compresses very well, so gzipping it is encouraged. If you want
+to examine the stream to see that it does not contain any private data,
+you can peruse it directly before sending. You may also want to try:
+
+---------------------------------------------------
+$ perl -pe 's/\d+/X/g' <anon-stream | sort -u | less
+---------------------------------------------------
+
+which shows all of the unique lines (with numbers converted to "X", to
+collapse "User 0", "User 1", etc into "User X"). This produces a much
+smaller output, and it is usually easy to quickly confirm that there is
+no private data in the stream.
+
+
Limitations
-----------
diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 875d2831a5..7d991d919c 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -38,18 +38,17 @@ Variables
imap.folder::
The folder to drop the mails into, which is typically the Drafts
folder. For example: "INBOX.Drafts", "INBOX/Drafts" or
- "[Gmail]/Drafts". Required to use imap-send.
+ "[Gmail]/Drafts". Required.
imap.tunnel::
Command used to setup a tunnel to the IMAP server through which
commands will be piped instead of using a direct network connection
- to the server. Required when imap.host is not set to use imap-send.
+ to the server. Required when imap.host is not set.
imap.host::
A URL identifying the server. Use a `imap://` prefix for non-secure
connections and a `imaps://` prefix for secure connections.
- Ignored when imap.tunnel is set, but required to use imap-send
- otherwise.
+ Ignored when imap.tunnel is set, but required otherwise.
imap.user::
The username to use when logging in to the server.
@@ -76,7 +75,8 @@ imap.preformattedHTML::
imap.authMethod::
Specify authenticate method for authentication with IMAP server.
- Current supported method is 'CRAM-MD5' only.
+ Current supported method is 'CRAM-MD5' only. If this is not set
+ then 'git imap-send' uses the basic IMAP plaintext LOGIN command.
Examples
~~~~~~~~
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index afd721e3a9..369f889bb4 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -43,7 +43,7 @@ OPTIONS
-q::
--quiet::
-Only print error and warning messages, all other output will be suppressed.
+Only print error and warning messages; all other output will be suppressed.
--bare::
@@ -57,12 +57,12 @@ DIRECTORY" section below.)
--separate-git-dir=<git dir>::
-Instead of initializing the repository where it is supposed to be,
-place a filesytem-agnostic Git symbolic link there, pointing to the
-specified path, and initialize a Git repository at the path. The
-result is Git repository can be separated from working tree. If this
-is reinitialization, the repository will be moved to the specified
-path.
+Instead of initializing the repository as a directory to either `$GIT_DIR` or
+`./.git/`, create a text file there containing the path to the actual
+repository. This file acts as filesystem-agnostic Git symbolic link to the
+repository.
++
+If this is reinitialization, the repository will be moved to the specified path.
--shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
@@ -72,60 +72,65 @@ repository. When specified, the config variable "core.sharedRepository" is
set so that files and directories under `$GIT_DIR` are created with the
requested permissions. When not specified, Git will use permissions reported
by umask(2).
-
++
The option can have the following values, defaulting to 'group' if no value
is given:
++
+--
+'umask' (or 'false')::
- - 'umask' (or 'false'): Use permissions reported by umask(2). The default,
- when `--shared` is not specified.
+Use permissions reported by umask(2). The default, when `--shared` is not
+specified.
- - 'group' (or 'true'): Make the repository group-writable, (and g+sx, since
- the git group may be not the primary group of all users).
- This is used to loosen the permissions of an otherwise safe umask(2) value.
- Note that the umask still applies to the other permission bits (e.g. if
- umask is '0022', using 'group' will not remove read privileges from other
- (non-group) users). See '0xxx' for how to exactly specify the repository
- permissions.
+'group' (or 'true')::
- - 'all' (or 'world' or 'everybody'): Same as 'group', but make the repository
- readable by all users.
+Make the repository group-writable, (and g+sx, since the git group may be not
+the primary group of all users). This is used to loosen the permissions of an
+otherwise safe umask(2) value. Note that the umask still applies to the other
+permission bits (e.g. if umask is '0022', using 'group' will not remove read
+privileges from other (non-group) users). See '0xxx' for how to exactly specify
+the repository permissions.
- - '0xxx': '0xxx' is an octal number and each file will have mode '0xxx'.
- '0xxx' will override users' umask(2) value (and not only loosen permissions
- as 'group' and 'all' does). '0640' will create a repository which is
- group-readable, but not group-writable or accessible to others. '0660' will
- create a repo that is readable and writable to the current user and group,
- but inaccessible to others.
+'all' (or 'world' or 'everybody')::
-By default, the configuration flag receive.denyNonFastForwards is enabled
+Same as 'group', but make the repository readable by all users.
+
+'0xxx'::
+
+'0xxx' is an octal number and each file will have mode '0xxx'. '0xxx' will
+override users' umask(2) value (and not only loosen permissions as 'group' and
+'all' does). '0640' will create a repository which is group-readable, but not
+group-writable or accessible to others. '0660' will create a repo that is
+readable and writable to the current user and group, but inaccessible to others.
+--
+
+By default, the configuration flag `receive.denyNonFastForwards` is enabled
in shared repositories, so that you cannot force a non fast-forwarding push
into it.
-If you name a (possibly non-existent) directory at the end of the command
-line, the command is run inside the directory (possibly after creating it).
+If you provide a 'directory', the command is run inside it. If this directory
+does not exist, it will be created.
--
-
TEMPLATE DIRECTORY
------------------
The template directory contains files and directories that will be copied to
the `$GIT_DIR` after it is created.
-The template directory used will (in order):
+The template directory will be one of the following (in order):
- - The argument given with the `--template` option.
+ - the argument given with the `--template` option;
- - The contents of the `$GIT_TEMPLATE_DIR` environment variable.
+ - the contents of the `$GIT_TEMPLATE_DIR` environment variable;
- - The `init.templatedir` configuration variable.
+ - the `init.templatedir` configuration variable; or
- - The default template directory: `/usr/share/git-core/templates`.
+ - the default template directory: `/usr/share/git-core/templates`.
-The default template directory includes some directory structure, some
-suggested "exclude patterns", and copies of sample "hook" files.
-The suggested patterns and hook files are all modifiable and extensible.
+The default template directory includes some directory structure, suggested
+"exclude patterns" (see linkgit:gitignore[5]), and sample hook files (see linkgit:githooks[5]).
EXAMPLES
--------
@@ -136,10 +141,12 @@ Start a new Git repository for an existing code base::
$ cd /path/to/my/codebase
$ git init <1>
$ git add . <2>
+$ git commit <3>
----------------
+
-<1> prepare /path/to/my/codebase/.git directory
-<2> add all existing file to the index
+<1> Create a /path/to/my/codebase/.git directory.
+<2> Add all existing files to the index.
+<3> Record the pristine state as the first commit in the history.
GIT
---
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 2a93c645bd..f14100a160 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -316,11 +316,8 @@ which makes little sense.
-f::
--force-rebase::
- Force the rebase even if the current branch is a descendant
- of the commit you are rebasing onto. Normally non-interactive rebase will
- exit with the message "Current branch is up to date" in such a
- situation.
- Incompatible with the --interactive option.
+ Force a rebase even if the current branch is up-to-date and
+ the command without `--force` would return without doing anything.
+
You may find this (or --no-ff with an interactive rebase) helpful after
reverting a topic branch merge, as this option recreates the topic branch with
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 7a1585def0..fd7f8b5bc1 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -45,7 +45,7 @@ SYNOPSIS
[ \--regexp-ignore-case | -i ]
[ \--extended-regexp | -E ]
[ \--fixed-strings | -F ]
- [ \--date=(local|relative|default|iso|rfc|short) ]
+ [ \--date=(local|relative|default|iso|iso-strict|rfc|short) ]
[ [\--objects | \--objects-edge] [ \--unpacked ] ]
[ \--pretty | \--header ]
[ \--bisect ]
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index dc3a568baa..2a0de42a75 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -35,6 +35,16 @@ OPTIONS
Instead of explicitly specifying which refs to update,
update all heads that locally exist.
+--stdin::
+ Take the list of refs from stdin, one per line. If there
+ are refs specified on the command line in addition to this
+ option, then the refs from stdin are processed after those
+ on the command line.
++
+If '--stateless-rpc' is specified together with this option then
+the list of refs must be in packet format (pkt-line). Each ref must
+be in a separate packet, and the list must end with a flush packet.
+
--dry-run::
Do everything except actually send the updates.
@@ -77,7 +87,8 @@ this flag.
Without '--all' and without any '<ref>', the heads that exist
both on the local side and on the remote side are updated.
-When one or more '<ref>' are specified explicitly, it can be either a
+When one or more '<ref>' are specified explicitly (whether on the
+command line or via `--stdin`), it can be either a
single pattern, or a pair of such pattern separated by a colon
":" (this means that a ref name cannot have a colon in it). A
single pattern '<name>' is just a shorthand for '<name>:<name>'.
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 44c970ce18..ef8ef1c545 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -386,11 +386,13 @@ Any other arguments are passed directly to 'git log'
tree-ish to specify which branch should be searched). When given a
tree-ish, returns the corresponding SVN revision number.
+
+-B;;
--before;;
Don't require an exact match if given an SVN revision, instead find
the commit corresponding to the state of the SVN repository (on the
current branch) at the specified revision.
+
+-A;;
--after;;
Don't require an exact match if given an SVN revision; if there is
not an exact match return the closest match searching forward in the
@@ -608,21 +610,6 @@ config key: svn.authorsfile
Make 'git svn' less verbose. Specify a second time to make it
even less verbose.
---repack[=<n>]::
---repack-flags=<flags>::
- These should help keep disk usage sane for large fetches with
- many revisions.
-+
---repack takes an optional argument for the number of revisions
-to fetch before repacking. This defaults to repacking every
-1000 commits fetched if no argument is specified.
-+
---repack-flags are passed directly to 'git repack'.
-+
-[verse]
-config key: svn.repack
-config key: svn.repackflags
-
-m::
--merge::
-s<strategy>::
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index dfc09d93d8..82eca6fdf6 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -202,7 +202,7 @@ merging.
To pretend you have a file with mode and sha1 at path, say:
----------------
-$ git update-index --cacheinfo mode sha1 path
+$ git update-index --cacheinfo <mode>,<sha1>,<path>
----------------
'--info-only' is used to register files without placing them in the object
diff --git a/Documentation/git.txt b/Documentation/git.txt
index de7b870a35..26de4dd548 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -452,6 +452,11 @@ example the following invocations are equivalent:
given will override values from configuration files.
The <name> is expected in the same format as listed by
'git config' (subkeys separated by dots).
++
+Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets
+`foo.bar` to the boolean true value (just like `[foo]bar` would in a
+config file). Including the equals but with an empty value (like `git -c
+foo.bar= ...`) sets `foo.bar` to the empty string.
--exec-path[=<path>]::
Path to wherever your core Git programs are installed.
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 643c1ba929..9b45bda748 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -440,8 +440,8 @@ Unspecified::
A path to which the `diff` attribute is unspecified
first gets its contents inspected, and if it looks like
- text, it is treated as text. Otherwise it would
- generate `Binary files differ`.
+ text and is smaller than core.bigFileThreshold, it is treated
+ as text. Otherwise it would generate `Binary files differ`.
String::
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 85d63532a3..6c30723740 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -115,18 +115,20 @@ The placeholders are:
- '%aD': author date, RFC2822 style
- '%ar': author date, relative
- '%at': author date, UNIX timestamp
-- '%ai': author date, ISO 8601 format
+- '%ai': author date, ISO 8601-like format
+- '%aI': author date, strict ISO 8601 format
- '%cn': committer name
- '%cN': committer name (respecting .mailmap, see
linkgit:git-shortlog[1] or linkgit:git-blame[1])
- '%ce': committer email
- '%cE': committer email (respecting .mailmap, see
linkgit:git-shortlog[1] or linkgit:git-blame[1])
-- '%cd': committer date
+- '%cd': committer date (format respects --date= option)
- '%cD': committer date, RFC2822 style
- '%cr': committer date, relative
- '%ct': committer date, UNIX timestamp
-- '%ci': committer date, ISO 8601 format
+- '%ci': committer date, ISO 8601-like format
+- '%cI': committer date, strict ISO 8601 format
- '%d': ref names, like the --decorate option of linkgit:git-log[1]
- '%e': encoding
- '%s': subject
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index deb8cca917..5d311b8d46 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -677,7 +677,7 @@ include::pretty-options.txt[]
--relative-date::
Synonym for `--date=relative`.
---date=(relative|local|default|iso|rfc|short|raw)::
+--date=(relative|local|default|iso|iso-strict|rfc|short|raw)::
Only takes effect for dates shown in human-readable format, such
as when using `--pretty`. `log.date` config variable sets a default
value for the log command's `--date` option.
@@ -687,7 +687,16 @@ e.g. ``2 hours ago''.
+
`--date=local` shows timestamps in user's local time zone.
+
-`--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format.
+`--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format.
+The differences to the strict ISO 8601 format are:
+
+ - a space instead of the `T` date/time delimiter
+ - a space between time and time zone
+ - no colon between hours and minutes of the time zone
+
++
+`--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict
+ISO 8601 format.
+
`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
format, often found in email messages.
diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
index edd5018e15..0d8b99b368 100644
--- a/Documentation/technical/api-config.txt
+++ b/Documentation/technical/api-config.txt
@@ -77,6 +77,99 @@ To read a specific file in git-config format, use
`git_config_from_file`. This takes the same callback and data parameters
as `git_config`.
+Querying For Specific Variables
+-------------------------------
+
+For programs wanting to query for specific variables in a non-callback
+manner, the config API provides two functions `git_config_get_value`
+and `git_config_get_value_multi`. They both read values from an internal
+cache generated previously from reading the config files.
+
+`int git_config_get_value(const char *key, const char **value)`::
+
+ Finds the highest-priority value for the configuration variable `key`,
+ stores the pointer to it in `value` and returns 0. When the
+ configuration variable `key` is not found, returns 1 without touching
+ `value`. The caller should not free or modify `value`, as it is owned
+ by the cache.
+
+`const struct string_list *git_config_get_value_multi(const char *key)`::
+
+ Finds and returns the value list, sorted in order of increasing priority
+ for the configuration variable `key`. When the configuration variable
+ `key` is not found, returns NULL. The caller should not free or modify
+ the returned pointer, as it is owned by the cache.
+
+`void git_config_clear(void)`::
+
+ Resets and invalidates the config cache.
+
+The config API also provides type specific API functions which do conversion
+as well as retrieval for the queried variable, including:
+
+`int git_config_get_int(const char *key, int *dest)`::
+
+ Finds and parses the value to an integer for the configuration variable
+ `key`. Dies on error; otherwise, stores the value of the parsed integer in
+ `dest` and returns 0. When the configuration variable `key` is not found,
+ returns 1 without touching `dest`.
+
+`int git_config_get_ulong(const char *key, unsigned long *dest)`::
+
+ Similar to `git_config_get_int` but for unsigned longs.
+
+`int git_config_get_bool(const char *key, int *dest)`::
+
+ Finds and parses the value into a boolean value, for the configuration
+ variable `key` respecting keywords like "true" and "false". Integer
+ values are converted into true/false values (when they are non-zero or
+ zero, respectively). Other values cause a die(). If parsing is successful,
+ stores the value of the parsed result in `dest` and returns 0. When the
+ configuration variable `key` is not found, returns 1 without touching
+ `dest`.
+
+`int git_config_get_bool_or_int(const char *key, int *is_bool, int *dest)`::
+
+ Similar to `git_config_get_bool`, except that integers are copied as-is,
+ and `is_bool` flag is unset.
+
+`int git_config_get_maybe_bool(const char *key, int *dest)`::
+
+ Similar to `git_config_get_bool`, except that it returns -1 on error
+ rather than dying.
+
+`int git_config_get_string_const(const char *key, const char **dest)`::
+
+ Allocates and copies the retrieved string into the `dest` parameter for
+ the configuration variable `key`; if NULL string is given, prints an
+ error message and returns -1. When the configuration variable `key` is
+ not found, returns 1 without touching `dest`.
+
+`int git_config_get_string(const char *key, char **dest)`::
+
+ Similar to `git_config_get_string_const`, except that retrieved value
+ copied into the `dest` parameter is a mutable string.
+
+`int git_config_get_pathname(const char *key, const char **dest)`::
+
+ Similar to `git_config_get_string`, but expands `~` or `~user` into
+ the user's home directory when found at the beginning of the path.
+
+`git_die_config(const char *key, const char *err, ...)`::
+
+ First prints the error message specified by the caller in `err` and then
+ dies printing the line number and the file name of the highest priority
+ value for the configuration variable `key`.
+
+`void git_die_config_linenr(const char *key, const char *filename, int linenr)`::
+
+ Helper function which formats the die error message according to the
+ parameters entered. Used by `git_die_config()`. It can be used by callers
+ handling `git_config_get_value_multi()` to print the correct error message
+ for the desired value.
+
+See test-config.c for usage examples.
+
Value Parsing Helpers
---------------------
@@ -134,6 +227,68 @@ int read_file_with_include(const char *file, config_fn_t fn, void *data)
`git_config` respects includes automatically. The lower-level
`git_config_from_file` does not.
+Custom Configsets
+-----------------
+
+A `config_set` can be used to construct an in-memory cache for
+config-like files that the caller specifies (i.e., files like `.gitmodules`,
+`~/.gitconfig` etc.). For example,
+
+---------------------------------------
+struct config_set gm_config;
+git_configset_init(&gm_config);
+int b;
+/* we add config files to the config_set */
+git_configset_add_file(&gm_config, ".gitmodules");
+git_configset_add_file(&gm_config, ".gitmodules_alt");
+
+if (!git_configset_get_bool(gm_config, "submodule.frotz.ignore", &b)) {
+ /* hack hack hack */
+}
+
+/* when we are done with the configset */
+git_configset_clear(&gm_config);
+----------------------------------------
+
+Configset API provides functions for the above mentioned work flow, including:
+
+`void git_configset_init(struct config_set *cs)`::
+
+ Initializes the config_set `cs`.
+
+`int git_configset_add_file(struct config_set *cs, const char *filename)`::
+
+ Parses the file and adds the variable-value pairs to the `config_set`,
+ dies if there is an error in parsing the file. Returns 0 on success, or
+ -1 if the file does not exist or is inaccessible. The user has to decide
+ if he wants to free the incomplete configset or continue using it when
+ the function returns -1.
+
+`int git_configset_get_value(struct config_set *cs, const char *key, const char **value)`::
+
+ Finds the highest-priority value for the configuration variable `key`
+ and config set `cs`, stores the pointer to it in `value` and returns 0.
+ When the configuration variable `key` is not found, returns 1 without
+ touching `value`. The caller should not free or modify `value`, as it
+ is owned by the cache.
+
+`const struct string_list *git_configset_get_value_multi(struct config_set *cs, const char *key)`::
+
+ Finds and returns the value list, sorted in order of increasing priority
+ for the configuration variable `key` and config set `cs`. When the
+ configuration variable `key` is not found, returns NULL. The caller
+ should not free or modify the returned pointer, as it is owned by the cache.
+
+`void git_configset_clear(struct config_set *cs)`::
+
+ Clears `config_set` structure, removes all saved variable-value pairs.
+
+In addition to above functions, the `config_set` API provides type specific
+functions in the vein of `git_config_get_int` and family but with an extra
+parameter, pointer to struct `config_set`.
+They all behave similarly to the `git_config_get*()` family described in
+"Querying For Specific Variables" above.
+
Writing Config Files
--------------------
diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt
index 69510ae57a..842b8389eb 100644
--- a/Documentation/technical/api-run-command.txt
+++ b/Documentation/technical/api-run-command.txt
@@ -13,6 +13,10 @@ produces in the caller in order to process it.
Functions
---------
+`child_process_init`
+
+ Initialize a struct child_process variable.
+
`start_command`::
Start a sub-process. Takes a pointer to a `struct child_process`
@@ -96,8 +100,8 @@ command to run in a sub-process.
The caller:
-1. allocates and clears (memset(&chld, 0, sizeof(chld));) a
- struct child_process variable;
+1. allocates and clears (using child_process_init() or
+ CHILD_PROCESS_INIT) a struct child_process variable;
2. initializes the members;
3. calls start_command();
4. processes the data;
diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt
index f9c06a7573..cca6543234 100644
--- a/Documentation/technical/api-strbuf.txt
+++ b/Documentation/technical/api-strbuf.txt
@@ -160,6 +160,10 @@ then they will free() it.
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
@@ -307,6 +311,16 @@ same behaviour as well.
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
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index 18dea8d15f..569c48a352 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -467,7 +467,7 @@ references.
----
update-request = *shallow command-list [pack-file]
- shallow = PKT-LINE("shallow" SP obj-id)
+ shallow = PKT-LINE("shallow" SP obj-id LF)
command-list = PKT-LINE(command NUL capability-list LF)
*PKT-LINE(command LF)