path: root/Documentation
diff options
Diffstat (limited to 'Documentation')
22 files changed, 565 insertions, 77 deletions
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 5f4d793..02776e5 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -992,6 +992,14 @@ commit.cleanup::
have to remove the help lines that begin with `#` in the commit log
template yourself, if you do this).
+ A boolean to specify whether all commits should be GPG signed.
+ Use of this option when doing operations such as rebase can
+ result in a large number of commits being signed. It may be
+ convenient to use an agent to avoid typing your GPG passphrase
+ several times.
A boolean to enable/disable inclusion of status information in the
commit message template when using an editor to prepare the commit
@@ -1167,6 +1175,10 @@ gc.autopacklimit::
--auto` consolidates them into one larger pack. The
default value is 50. Setting this to 0 disables it.
+ Make `git gc --auto` return immediately andrun in background
+ if the system supports it. Default is true.
Running `git pack-refs` in a repository renders it
unclonable by Git versions prior to over dumb
@@ -1862,6 +1874,31 @@ pack.packSizeLimit::
Common unit suffixes of 'k', 'm', or 'g' are
+ When true, git will use pack bitmaps (if available) when packing
+ to stdout (e.g., during the server side of a fetch). Defaults to
+ true. You should not generally need to turn this off unless
+ you are debugging pack bitmaps.
+ When true, git will write a bitmap index when packing all
+ objects to disk (e.g., when `git repack -a` is run). This
+ index can speed up the "counting objects" phase of subsequent
+ packs created for clones and fetches, at the cost of some disk
+ space and extra time spent on the initial repack. Defaults to
+ false.
+ When true, git will include a "hash cache" section in the bitmap
+ index (if one is written). This cache can be used to feed git's
+ delta heuristics, potentially leading to better deltas between
+ bitmapped and non-bitmapped objects (e.g., when serving a fetch
+ between an older, bitmapped pack and objects that have been
+ pushed since the last gc). The downside is that it consumes 4
+ bytes per object of disk space, and that JGit's bitmap
+ implementation does not understand it, causing it to complain if
+ Git and JGit are used on the same repository. Defaults to false.
If the value is boolean, turns on or off pagination of the
output of a particular Git subcommand when writing to a tty.
@@ -1881,6 +1918,16 @@ pretty.<name>::
Note that an alias with the same name as a built-in format
will be silently ignored.
+ By default, Git does not create an extra merge commit when merging
+ a commit that is a descendant of the current commit. Instead, the
+ tip of the current branch is fast-forwarded. When set to `false`,
+ this variable tells Git to create an extra merge commit in such
+ a case (equivalent to giving the `--no-ff` option from the command
+ line). When set to `only`, only such fast-forward merges are
+ allowed (equivalent to giving the `--ff-only` option from the
+ command line).
When true, rebase branches on top of the fetched branch, instead
of merging the default branch from the default remote when "git
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 54d8461..17924d0 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -14,7 +14,7 @@ SYNOPSIS
[--ignore-date] [--ignore-space-change | --ignore-whitespace]
[--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>]
[--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet]
- [--[no-]scissors]
+ [--[no-]scissors] [-S[<keyid>]]
[(<mbox> | <Maildir>)...]
'git am' (--continue | --skip | --abort)
@@ -119,6 +119,10 @@ default. You can use `--no-utf8` to override this.
Skip the current patch. This is only meaningful when
restarting an aborted patch.
+ GPG-sign commits.
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index 8e70a61..9f23a86 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -35,7 +35,8 @@ Apart from supporting file annotation, Git also supports searching the
development history for when a code snippet occurred in a change. This makes it
possible to track when a code snippet was added to a file, moved or copied
between files, and eventually deleted or replaced. It works by searching for
-a text string in the diff. A small example:
+a text string in the diff. A small example of the pickaxe interface
+that searches for `blame_usage`:
$ git log --pretty=oneline -S'blame_usage'
diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index c205d23..f1e6b2f 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -8,7 +8,8 @@ git-cherry-pick - Apply the changes introduced by some existing commits
-'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit>...
+'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]
+ [-S[<keyid>]] <commit>...
'git cherry-pick' --continue
'git cherry-pick' --quit
'git cherry-pick' --abort
@@ -100,6 +101,10 @@ effect to your index in a row.
Add Signed-off-by line at the end of the commit message.
+ GPG-sign commits.
If the current HEAD is the same as the parent of the
cherry-pick'ed commit, then a fast forward to this commit will
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index bf3dac0..0363d00 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -55,15 +55,12 @@ repository is specified as a URL, then this flag is ignored (and we
never use the local optimizations). Specifying `--no-local` will
override the default when `/path/to/repo` is given, using the regular
Git transport instead.
-To force copying instead of hardlinking (which may be desirable if you
-are trying to make a back-up of your repository), but still avoid the
-usual "Git aware" transport mechanism, `--no-hardlinks` can be used.
- Optimize the cloning process from a repository on a
- local filesystem by copying files under `.git/objects`
- directory.
+ Force the cloning process from a repository on a local
+ filesystem to copy the files under the `.git/objects`
+ directory instead of using hardlinks. This may be desirable
+ if you are trying to make a back-up of your repository.
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index cafdc96..a469eab 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -55,8 +55,13 @@ OPTIONS
from the standard input.
GPG-sign commit.
+ Countermand `commit.gpgsign` configuration variable that is
+ set to force each and every commit to be signed.
Commit Information
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 1a7616c..7c42e9c 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -302,6 +302,10 @@ configuration variable documented in linkgit:git-config[1].
GPG-sign commit.
+ Countermand `commit.gpgsign` configuration variable that is
+ set to force each and every commit to be signed.
Do not interpret any more arguments as options.
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 2889be6..2a93c64 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -281,6 +281,10 @@ which makes little sense.
specified, `-s recursive`. Note the reversal of 'ours' and
'theirs' as noted above for the `-m` option.
+ GPG-sign commits.
Be quiet. Implies --no-stat.
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index 2507c8b..cb103c8 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -3,7 +3,7 @@ git-remote(1)
-git-remote - manage set of tracked repositories
+git-remote - Manage set of tracked repositories
diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index 509cf73..002cfd5 100644
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -9,7 +9,7 @@ git-repack - Pack unpacked objects in a repository
-'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=<n>] [--depth=<n>]
+'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [--window=<n>] [--depth=<n>]
@@ -110,6 +110,13 @@ other objects in that pack they already have locally.
The default is unlimited, unless the config variable
`pack.packSizeLimit` is set.
+ Write a reachability bitmap index as part of the repack. This
+ only makes sense when used with `-a` or `-A`, as the bitmaps
+ must be able to refer to all reachable objects. This option
+ overrides the setting of `pack.writebitmaps`.
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt
index f445cb3..a077ba0 100644
--- a/Documentation/git-reset.txt
+++ b/Documentation/git-reset.txt
@@ -10,7 +10,7 @@ SYNOPSIS
'git reset' [-q] [<tree-ish>] [--] <paths>...
'git reset' (--patch | -p) [<tree-ish>] [--] [<paths>...]
-'git reset' [--soft | --mixed | --hard | --merge | --keep] [-q] [<commit>]
+'git reset' [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] [<commit>]
@@ -60,6 +60,9 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
Resets the index but not the working tree (i.e., the changed files
are preserved but not marked for commit) and reports what has not
been updated. This is the default action.
+If `-N` is specified, removed paths are marked as intent-to-add (see
Resets the index and working tree. Any changes to tracked files in the
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 045b37b..7a1585d 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -55,6 +55,7 @@ SYNOPSIS
[ \--reverse ]
[ \--walk-reflogs ]
[ \--no-walk ] [ \--do-walk ]
+ [ \--use-bitmap-index ]
<commit>... [ \-- <paths>... ]
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 2de67a5..9eb83f0 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -8,7 +8,7 @@ git-revert - Revert some existing commits
-'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] <commit>...
+'git revert' [--[no-]edit] [-n] [-m parent-number] [-s] [-S[<keyid>]] <commit>...
'git revert' --continue
'git revert' --quit
'git revert' --abort
@@ -80,6 +80,10 @@ more details.
This is useful when reverting more than one commits'
effect to your index in a row.
+ GPG-sign commits.
Add Signed-off-by line at the end of the commit message.
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index bfef8a0..21cb59a 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -15,8 +15,8 @@ SYNOPSIS
'git submodule' [--quiet] init [--] [<path>...]
'git submodule' [--quiet] deinit [-f|--force] [--] <path>...
'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
- [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>]
- [--merge] [--recursive] [--] [<path>...]
+ [-f|--force] [--rebase|--merge|--checkout] [--reference <repository>]
+ [--depth <depth>] [--recursive] [--] [<path>...]
'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
[commit] [--] [<path>...]
'git submodule' [--quiet] foreach [--recursive] <command>
@@ -155,13 +155,31 @@ it contains local modifications.
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.
+ checkout the commit specified in the index of the containing
+ repository. The update mode defaults to `checkout`, but can be
+ configured with the `submodule.<name>.update` setting or the
+ `--rebase`, `--merge`, or `--checkout` options.
+For updates that clone missing submodules, checkout-mode updates will
+create submodules with detached HEADs; all other modes will create
+submodules with a local branch named after `submodule.<path>.branch`.
+For updates that do not clone missing submodules, the submodule's HEAD
+is only touched when the remote reference does not match the
+submodule's HEAD (for none-mode updates, the submodule is never
+touched). The remote reference is usually the gitlinked commit from
+the superproject's tree, but with `--remote` it is the upstream
+subproject's `submodule.<name>.branch`. This remote reference is
+integrated with the submodule's HEAD using the specified update mode.
+For checkout-mode updates, that will result in a detached HEAD. For
+rebase- and merge-mode updates, the commit referenced by the
+submodule's HEAD may change, but the symbolic reference will remain
+unchanged (i.e. checked-out branches will still be checked-out
+branches, and detached HEADs will still be detached HEADs). If none
+of the builtin modes fit your needs, set `submodule.<name>.update` to
+`!command` to configure a custom integration command. `command` can
+be any arbitrary shell command that takes a single argument, namely
+the sha1 to update to.
If the submodule is not yet initialized, and you just want to use the
setting as stored in .gitmodules, you can automatically initialize the
@@ -281,6 +299,16 @@ In order to ensure a current tracking branch state, `update --remote`
fetches the submodule's remote repository before calculating the
SHA-1. If you don't want to fetch, you should use `submodule update
--remote --no-fetch`.
+Use this option to integrate changes from the upstream subproject with
+your submodule's current HEAD. Alternatively, you can run `git pull`
+from the submodule, which is equivalent except for the remote branch
+name: `update --remote` uses the default upstream repository and
+`submodule.<name>.branch`, while `git pull` uses the submodule's
+`branch.<name>.merge`. Prefer `submodule.<name>.branch` if you want
+to distribute the default upstream branch with the superproject and
+`branch.<name>.merge` if you want a more native feel while working in
+the submodule itself.
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index 347a9f7..f539e3f 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -55,6 +55,10 @@ submodule.<name>.branch::
A remote branch name for tracking updates in the upstream submodule.
If the option is not specified, it defaults to 'master'. See the
`--remote` documentation in linkgit:git-submodule[1] for details.
+This branch name is also used for the local branch created by
+non-checkout cloning updates. See the `update` documentation in
+linkgit:git-submodule[1] for details.
This option can be used to control recursive fetching of this
diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
index fb6e593..3509498 100644
--- a/Documentation/merge-strategies.txt
+++ b/Documentation/merge-strategies.txt
@@ -20,7 +20,7 @@ recursive::
merged tree of the common ancestors and uses that as
the reference tree for the 3-way merge. This has been
reported to result in fewer merge conflicts without
- causing mis-merges by tests done on actual merge commits
+ causing mismerges by tests done on actual merge commits
taken from Linux 2.6 kernel development history.
Additionally this can detect and handle merges involving
renames. This is the default merge strategy when
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 03533af..9a3da36 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -257,6 +257,14 @@ See also linkgit:git-reflog[1].
Output excluded boundary commits. Boundary commits are
prefixed with `-`.
+ Try to speed up the traversal using the pack bitmap index (if
+ one is available). Note that when traversing with `--objects`,
+ trees and blobs will not have their associated path printed.
History Simplification
diff --git a/Documentation/technical/api-hash.txt b/Documentation/technical/api-hash.txt
deleted file mode 100644
index e5061e0..0000000
--- a/Documentation/technical/api-hash.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-hash API
-The hash API is a collection of simple hash table functions. Users are expected
-to implement their own hashing.
-Data Structures
-`struct hash_table`::
- The hash table structure. The `array` member points to the hash table
- entries. The `size` member counts the total number of valid and invalid
- entries in the table. The `nr` member keeps track of the number of
- valid entries.
-`struct hash_table_entry`::
- An opaque structure representing an entry in the hash table. The `hash`
- member is the entry's hash key and the `ptr` member is the entry's
- value.
- Initialize the hash table.
- Release memory associated with the hash table.
- Insert a pointer into the hash table. If an entry with that hash
- already exists, a pointer to the existing entry's value is returned.
- Otherwise NULL is returned. This allows callers to implement
- chaining, etc.
- Lookup an entry in the hash table. If an entry with that hash exists
- the entry's value is returned. Otherwise NULL is returned.
- Call a function for each entry in the hash table. The function is
- expected to take the entry's value as its only argument and return an
- int. If the function returns a negative int the loop is aborted
- immediately. Otherwise, the return value is accumulated and the sum
- returned upon completion of the loop.
diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt
new file mode 100644
index 0000000..42ca234
--- /dev/null
+++ b/Documentation/technical/api-hashmap.txt
@@ -0,0 +1,235 @@
+hashmap API
+The hashmap API is a generic implementation of hash-based key-value mappings.
+Data Structures
+`struct hashmap`::
+ The hash table structure.
+The `size` member keeps track of the total number of entries. The `cmpfn`
+member is a function used to compare two entries for equality. The `table` and
+`tablesize` members store the hash table and its size, respectively.
+`struct hashmap_entry`::
+ An opaque structure representing an entry in the hash table, which must
+ be used as first member of user data structures. Ideally it should be
+ followed by an int-sized member to prevent unused memory on 64-bit
+ systems due to alignment.
+The `hash` member is the entry's hash code and the `next` member points to the
+next entry in case of collisions (i.e. if multiple entries map to the same
+`struct hashmap_iter`::
+ An iterator structure, to be used with hashmap_iter_* functions.
+`int (*hashmap_cmp_fn)(const void *entry, const void *entry_or_key, const void *keydata)`::
+ User-supplied function to test two hashmap entries for equality. Shall
+ return 0 if the entries are equal.
+This function is always called with non-NULL `entry` / `entry_or_key`
+parameters that have the same hash code. When looking up an entry, the `key`
+and `keydata` parameters to hashmap_get and hashmap_remove are always passed
+as second and third argument, respectively. Otherwise, `keydata` is NULL.
+`unsigned int strhash(const char *buf)`::
+`unsigned int strihash(const char *buf)`::
+`unsigned int memhash(const void *buf, size_t len)`::
+`unsigned int memihash(const void *buf, size_t len)`::
+ Ready-to-use hash functions for strings, using the FNV-1 algorithm (see
+`strhash` and `strihash` take 0-terminated strings, while `memhash` and
+`memihash` operate on arbitrary-length memory.
+`strihash` and `memihash` are case insensitive versions.
+`void hashmap_init(struct hashmap *map, hashmap_cmp_fn equals_function, size_t initial_size)`::
+ Initializes a hashmap structure.
+`map` is the hashmap to initialize.
+The `equals_function` can be specified to compare two entries for equality.
+If NULL, entries are considered equal if their hash codes are equal.
+If the total number of entries is known in advance, the `initial_size`
+parameter may be used to preallocate a sufficiently large table and thus
+prevent expensive resizing. If 0, the table is dynamically resized.
+`void hashmap_free(struct hashmap *map, int free_entries)`::
+ Frees a hashmap structure and allocated memory.
+`map` is the hashmap to free.
+If `free_entries` is true, each hashmap_entry in the map is freed as well
+(using stdlib's free()).
+`void hashmap_entry_init(void *entry, unsigned int hash)`::
+ Initializes a hashmap_entry structure.
+`entry` points to the entry to initialize.
+`hash` is the hash code of the entry.
+`void *hashmap_get(const struct hashmap *map, const void *key, const void *keydata)`::
+ Returns the hashmap entry for the specified key, or NULL if not found.
+`map` is the hashmap structure.
+`key` is a hashmap_entry structure (or user data structure that starts with
+hashmap_entry) that has at least been initialized with the proper hash code
+(via `hashmap_entry_init`).
+If an entry with matching hash code is found, `key` and `keydata` are passed
+to `hashmap_cmp_fn` to decide whether the entry matches the key.
+`void *hashmap_get_next(const struct hashmap *map, const void *entry)`::
+ Returns the next equal hashmap entry, or NULL if not found. This can be
+ used to iterate over duplicate entries (see `hashmap_add`).
+`map` is the hashmap structure.
+`entry` is the hashmap_entry to start the search from, obtained via a previous
+call to `hashmap_get` or `hashmap_get_next`.
+`void hashmap_add(struct hashmap *map, void *entry)`::
+ Adds a hashmap entry. This allows to add duplicate entries (i.e.
+ separate values with the same key according to hashmap_cmp_fn).
+`map` is the hashmap structure.
+`entry` is the entry to add.
+`void *hashmap_put(struct hashmap *map, void *entry)`::
+ Adds or replaces a hashmap entry. If the hashmap contains duplicate
+ entries equal to the specified entry, only one of them will be replaced.
+`map` is the hashmap structure.
+`entry` is the entry to add or replace.
+Returns the replaced entry, or NULL if not found (i.e. the entry was added).
+`void *hashmap_remove(struct hashmap *map, const void *key, const void *keydata)`::
+ Removes a hashmap entry matching the specified key. If the hashmap
+ contains duplicate entries equal to the specified key, only one of
+ them will be removed.
+`map` is the hashmap structure.
+`key` is a hashmap_entry structure (or user data structure that starts with
+hashmap_entry) that has at least been initialized with the proper hash code
+(via `hashmap_entry_init`).
+If an entry with matching hash code is found, `key` and `keydata` are
+passed to `hashmap_cmp_fn` to decide whether the entry matches the key.
+Returns the removed entry, or NULL if not found.
+`void hashmap_iter_init(struct hashmap *map, struct hashmap_iter *iter)`::
+`void *hashmap_iter_next(struct hashmap_iter *iter)`::
+`void *hashmap_iter_first(struct hashmap *map, struct hashmap_iter *iter)`::
+ Used to iterate over all entries of a hashmap.
+`hashmap_iter_init` initializes a `hashmap_iter` structure.
+`hashmap_iter_next` returns the next hashmap_entry, or NULL if there are no
+more entries.
+`hashmap_iter_first` is a combination of both (i.e. initializes the iterator
+and returns the first entry, if any).
+Usage example
+Here's a simple usage example that maps long keys to double values.
+struct hashmap map;
+struct long2double {
+ struct hashmap_entry ent; /* must be the first member! */
+ long key;
+ double value;
+static int long2double_cmp(const struct long2double *e1, const struct long2double *e2, const void *unused)
+ return !(e1->key == e2->key);
+void long2double_init(void)
+ hashmap_init(&map, (hashmap_cmp_fn) long2double_cmp, 0);
+void long2double_free(void)
+ hashmap_free(&map, 1);
+static struct long2double *find_entry(long key)
+ struct long2double k;
+ hashmap_entry_init(&k, memhash(&key, sizeof(long)));
+ k.key = key;
+ return hashmap_get(&map, &k, NULL);
+double get_value(long key)
+ struct long2double *e = find_entry(key);
+ return e ? e->value : 0;
+void set_value(long key, double value)
+ struct long2double *e = find_entry(key);
+ if (!e) {
+ e = malloc(sizeof(struct long2double));
+ hashmap_entry_init(e, memhash(&key, sizeof(long)));
+ e->key = key;
+ hashmap_add(&map, e);
+ }
+ e->value = value;
+Using variable-sized keys
+The `hashmap_entry_get` and `hashmap_entry_remove` functions expect an ordinary
+`hashmap_entry` structure as key to find the correct entry. If the key data is
+variable-sized (e.g. a FLEX_ARRAY string) or quite large, it is undesirable
+to create a full-fledged entry structure on the heap and copy all the key data
+into the structure.
+In this case, the `keydata` parameter can be used to pass
+variable-sized key data directly to the comparison function, and the `key`
+parameter can be a stripped-down, fixed size entry structure allocated on the
+See test-hashmap.c for an example using arbitrary-length strings as keys.
diff --git a/Documentation/technical/bitmap-format.txt b/Documentation/technical/bitmap-format.txt
new file mode 100644
index 0000000..f8c18a0
--- /dev/null
+++ b/Documentation/technical/bitmap-format.txt
@@ -0,0 +1,164 @@
+GIT bitmap v1 format
+ - A header appears at the beginning:
+ 4-byte signature: {'B', 'I', 'T', 'M'}
+ 2-byte version number (network byte order)
+ The current implementation only supports version 1
+ of the bitmap index (the same one as JGit).
+ 2-byte flags (network byte order)
+ The following flags are supported:
+ This flag must always be present. It implies that the bitmap
+ index has been generated for a packfile with full closure
+ (i.e. where every single object in the packfile can find
+ its parent links inside the same packfile). This is a
+ requirement for the bitmap index format, also present in JGit,
+ that greatly reduces the complexity of the implementation.
+ If present, the end of the bitmap file contains
+ `N` 32-bit name-hash values, one per object in the
+ pack. The format and meaning of the name-hash is
+ described below.
+ 4-byte entry count (network byte order)
+ The total count of entries (bitmapped commits) in this bitmap index.
+ 20-byte checksum
+ The SHA1 checksum of the pack this bitmap index belongs to.
+ - 4 EWAH bitmaps that act as type indexes
+ Type indexes are serialized after the hash cache in the shape
+ of four EWAH bitmaps stored consecutively (see Appendix A for
+ the serialization format of an EWAH bitmap).
+ There is a bitmap for each Git object type, stored in the following
+ order:
+ - Commits
+ - Trees
+ - Blobs
+ - Tags
+ In each bitmap, the `n`th bit is set to true if the `n`th object
+ in the packfile is of that type.
+ The obvious consequence is that the OR of all 4 bitmaps will result
+ in a full set (all bits set), and the AND of all 4 bitmaps will
+ result in an empty bitmap (no bits set).
+ - N entries with compressed bitmaps, one for each indexed commit
+ Where `N` is the total amount of entries in this bitmap index.
+ Each entry contains the following:
+ - 4-byte object position (network byte order)
+ The position **in the index for the packfile** where the
+ bitmap for this commit is found.
+ - 1-byte XOR-offset
+ The xor offset used to compress this bitmap. For an entry
+ in position `x`, a XOR offset of `y` means that the actual
+ bitmap representing this commit is composed by XORing the
+ bitmap for this entry with the bitmap in entry `x-y` (i.e.
+ the bitmap `y` entries before this one).
+ Note that this compression can be recursive. In order to
+ XOR this entry with a previous one, the previous entry needs
+ to be decompressed first, and so on.
+ The hard-limit for this offset is 160 (an entry can only be
+ xor'ed against one of the 160 entries preceding it). This
+ number is always positive, and hence entries are always xor'ed
+ with **previous** bitmaps, not bitmaps that will come afterwards
+ in the index.
+ - 1-byte flags for this bitmap
+ At the moment the only available flag is `0x1`, which hints
+ that this bitmap can be re-used when rebuilding bitmap indexes
+ for the repository.
+ - The compressed bitmap itself, see Appendix A.
+== Appendix A: Serialization format for an EWAH bitmap
+Ewah bitmaps are serialized in the same protocol as the JAVAEWAH
+library, making them backwards compatible with the JGit
+ - 4-byte number of bits of the resulting UNCOMPRESSED bitmap
+ - 4-byte number of words of the COMPRESSED bitmap, when stored
+ - N x 8-byte words, as specified by the previous field
+ This is the actual content of the compressed bitmap.
+ - 4-byte position of the current RLW for the compressed
+ bitmap
+All words are stored in network byte order for their corresponding
+The compressed bitmap is stored in a form of run-length encoding, as
+follows. It consists of a concatenation of an arbitrary number of
+chunks. Each chunk consists of one or more 64-bit words
+ H L_1 L_2 L_3 .... L_M
+H is called RLW (run length word). It consists of (from lower to higher
+order bits):
+ - 1 bit: the repeated bit B
+ - 32 bits: repetition count K (unsigned)
+ - 31 bits: literal word count M (unsigned)
+The bitstream represented by the above chunk is then:
+ - K repetitions of B
+ - The bits stored in `L_1` through `L_M`. Within a word, bits at
+ lower order come earlier in the stream than those at higher
+ order.
+The next word after `L_M` (if any) must again be a RLW, for the next
+chunk. For efficient appending to the bitstream, the EWAH stores a
+pointer to the last RLW in the stream.
+== Appendix B: Optional Bitmap Sections
+These sections may or may not be present in the `.bitmap` file; their
+presence is indicated by the header flags section described above.
+Name-hash cache
+If the BITMAP_OPT_HASH_CACHE flag is set, the end of the bitmap contains
+a cache of 32-bit values, one per object in the pack. The value at
+position `i` is the hash of the pathname at which the `i`th object
+(counting in index order) in the pack can be found. This can be fed
+into the delta heuristics to compare objects with similar pathnames.
+The hash algorithm used is:
+ hash = 0;
+ while ((c = *name++))
+ if (!isspace(c))
+ hash = (hash >> 2) + (c << 24);
+Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.
+If implementations want to choose a different hashing scheme, they are
+free to do so, but MUST allocate a new header flag (because comparing
+hashes made under two different schemes would be pointless).
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index c73b62f..39c6410 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -338,7 +338,8 @@ during a prior round. This helps to ensure that at least one common
ancestor is found before we give up entirely.
Once the 'done' line is read from the client, the server will either
-send a final 'ACK obj-id' or it will send a 'NAK'. The server only sends
+send a final 'ACK obj-id' or it will send a 'NAK'. 'obj-id' is the object
+name of the last commit determined to be common. The server only sends
ACK after 'done' if there is at least one common base and multi_ack or
multi_ack_detailed is enabled. The server always sends NAK after 'done'
if there is no common base found.
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
index e3e7924..e174343 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/technical/protocol-capabilities.txt
@@ -69,6 +69,24 @@ ends.
Without multi_ack the client would have sent that c-b-a chain anyway,
interleaved with S-R-Q.
+This is an extension of multi_ack that permits client to better
+understand the server's in-memory state. See pack-protocol.txt,
+section "Packfile Negotiation" for more information.
+This capability should only be used with the smart HTTP protocol. If
+multi_ack_detailed and no-done are both present, then the sender is
+free to immediately send a pack following its first "ACK obj-id ready"
+Without no-done in the smart HTTP protocol, the server session would
+end and the client has to make another trip to send "done" before
+the server can send the pack. no-done removes the last round and
+thus slightly reduces latency.