diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/CodingGuidelines | 9 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.0.2.txt | 19 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.1.0.txt | 36 | ||||
| -rw-r--r-- | Documentation/config.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-replace.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-rev-parse.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-tag.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-update-index.txt | 11 | ||||
| -rw-r--r-- | Documentation/git.txt | 62 | ||||
| -rw-r--r-- | Documentation/gitrepository-layout.txt | 4 | ||||
| -rw-r--r-- | Documentation/technical/api-hashmap.txt | 54 | ||||
| -rw-r--r-- | Documentation/technical/api-trace.txt | 97 | ||||
| -rw-r--r-- | Documentation/technical/index-format.txt | 35 |
13 files changed, 325 insertions, 26 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 4d90c77..894546d 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -404,6 +404,15 @@ For Python scripts: documentation for version 2.6 does not mention this prefix, it has been supported since version 2.6.0. +Error Messages + + - Do not end error messages with a full stop. + + - Do not capitalize ("unable to open %s", not "Unable to open %s") + + - Say what the error is first ("cannot open %s", not "%s: cannot open") + + Writing Documentation: Most (if not all) of the documentation pages are written in the diff --git a/Documentation/RelNotes/2.0.2.txt b/Documentation/RelNotes/2.0.2.txt index c48c0aa..8e8321b 100644 --- a/Documentation/RelNotes/2.0.2.txt +++ b/Documentation/RelNotes/2.0.2.txt @@ -11,3 +11,22 @@ Git v2.0.2 Release Notes * Recent updates to "git repack" started to duplicate objects that are in packfiles marked with .keep flag into the new packfile by mistake. + + * "git clone -b brefs/tags/bar" would have mistakenly thought we were + following a single tag, even though it was a name of the branch, + because it incorrectly used strstr(). + + * "%G" (nothing after G) is an invalid pretty format specifier, but + the parser did not notice it as garbage. + + * Code to avoid adding the same alternate object store twice was + subtly broken for a long time, but nobody seems to have noticed. + + * A handful of code paths had to read the commit object more than + once when showing header fields that are usually not parsed. The + internal data structure to keep track of the contents of the commit + object has been updated to reduce the need for this double-reading, + and to allow the caller find the length of the object. + + * During "git rebase --merge", a conflicted patch could not be + skipped with "--skip" if the next one also conflicted. diff --git a/Documentation/RelNotes/2.1.0.txt b/Documentation/RelNotes/2.1.0.txt index 3b65461..13c7ec5 100644 --- a/Documentation/RelNotes/2.1.0.txt +++ b/Documentation/RelNotes/2.1.0.txt @@ -93,7 +93,8 @@ UI, Workflows & Features users need to explicitly set the variable to 'true' if they want to resurrect the now-ignored use case. - * "git replace" learned the "--edit" subcommand. + * "git replace" learned the "--edit" subcommand to create a + replacement by editing an existing object. * "git send-email" learned "--to-cover" and "--cc-cover" options, to tell it to copy To: and Cc: headers found in the first input file @@ -115,6 +116,14 @@ Performance, Internal Implementation, etc. * Build procedure for 'subtree' (in contrib/) has been cleaned up. + * The support for the profile-feedback build, which has been left + bit-rotten for quite a while, has been updated. + + * An experimental format to use two files (the base file and + incremental changes relative to it) to represent the index has been + introduced; this may reduce I/O cost of rewriting a large index + when only small part of the working tree changes. + * Effort to shrink the size of patches Windows folks maintain on top by upstreaming them continues. @@ -141,6 +150,9 @@ Performance, Internal Implementation, etc. example, "update-ref --stdin [-z]" has been updated to use this API. + * skip_prefix() and strip_suffix() API functions are used a lot more + widely throughout the codebase now. + * Parts of the test scripts can be skipped by using a range notation, e.g. "sh t1234-test.sh --run='1-4 6 8-'" to omit test piece 5 and 7 and run everything else. @@ -185,6 +197,7 @@ notes for details). * Code to avoid adding the same alternate object store twice was subtly broken for a long time, but nobody seems to have noticed. (merge 80b4785 rs/fix-alt-odb-path-comparison later to maint). + (merge 539e750 ek/alt-odb-entry-fix later to maint). * The "%<(10,trunc)%s" pretty format specifier in the log family of commands is used to truncate the string to a given length (e.g. 10 @@ -213,6 +226,10 @@ notes for details). couple of options unique to "git merge". (merge 8fee872 jk/complete-merge-pull later to maint). + * An ancient rewrite passed a wrong pointer to a curl library + function in a rarely used code path. + (merge 479eaa8 ah/fix-http-push later to maint). + * "--ignore-space-change" option of "git apply" ignored the spaces at the beginning of line too aggressively, which is inconsistent with the option of the same name "diff" and "git diff" have. @@ -242,6 +259,11 @@ notes for details). bit. (merge 5304810 jk/diff-files-assume-unchanged later to maint). + * "filter-branch" left an empty single-parent commit that results when + all parents of a merge commit gets mapped to the same commit, even + under "--prune-empty". + (merge 79bc4ef cb/filter-branch-prune-empty-degenerate-merges later to maint). + * "git format-patch" did not enforce the rule that the "--follow" option from the log/diff family of commands must be used with exactly one pathspec. @@ -267,6 +289,13 @@ notes for details). distinguish missing objects from type errors. (merge 77583e7 jk/index-pack-report-missing later to maint). + * "log --show-signature" incorrectly decided the color to paint a + mergetag that was and was not correctly validated. + (merge 42c55ce mg/fix-log-mergetag-color later to maint). + + * "log --show-signature" did not pay attention to "--graph" option. + (merge cf3983d zk/log-graph-showsig later to maint). + * "git mailinfo" used to read beyond the end of header string while parsing an incoming e-mail message to extract the patch. (merge b1a013d rs/mailinfo-header-cmp later to maint). @@ -276,6 +305,11 @@ notes for details). except for case differences. (merge baa37bf dt/merge-recursive-case-insensitive later to maint). + * Merging changes into a file that ends in an incomplete line made the + last line into a complete one, even when the other branch did not + change anything around the end of file. + (merge ba31180 mk/merge-incomplete-files later to maint). + * "git pack-objects" unnecessarily copied the previous contents when extending the hashtable, even though it will populate the table from scratch anyway. diff --git a/Documentation/config.txt b/Documentation/config.txt index 1d718bd..c55c22a 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -2354,6 +2354,11 @@ submodule.<name>.ignore:: "--ignore-submodules" option. The 'git submodule' commands are not affected by this setting. +tag.sort:: + This variable controls the sort ordering of tags when displayed by + linkgit:git-tag[1]. Without the "--sort=<value>" option provided, the + value of this variable will be used as the default. + tar.umask:: This variable can be used to restrict the permission bits of tar archive entries. The default is 0002, which turns off the diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 61461b9..089dcac 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -73,6 +73,14 @@ OPTIONS newly created object. See linkgit:git-var[1] for details about how the editor will be chosen. +--raw:: + When editing, provide the raw object contents rather than + pretty-printed ones. Currently this only affects trees, which + will be shown in their binary form. This is harder to work with, + but can help when repairing a tree that is so corrupted it + cannot be pretty-printed. Note that you may need to configure + your editor to cleanly read and write binary data. + -l <pattern>:: --list <pattern>:: List replace refs for objects that match the given pattern (or diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 987395d..0b84769 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -102,7 +102,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" + If you want to make sure that the output actually names an object in your object database and/or can be used as a specific type of object -you require, you can add "^{type}" peeling operator to the parameter. +you require, you can add "\^{type}" peeling operator to the parameter. For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR` names an existing object that is a commit-ish (i.e. a commit, or an annotated tag that points at a commit). To make sure that `$VAR` @@ -245,6 +245,10 @@ print a message to stderr and exit with nonzero status. --show-toplevel:: Show the absolute path of the top-level directory. +--shared-index-path:: + Show the path to the shared index file in split index mode, or + empty if not in split-index mode. + Other Options ~~~~~~~~~~~~~ diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index b424a1b..3209083 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -99,7 +99,9 @@ OPTIONS Sort in a specific order. Supported type is "refname" (lexicographic order), "version:refname" or "v:refname" (tag names are treated as versions). Prepend "-" to reverse sort - order. + order. When this option is not given, the sort order defaults to the + value configured for the 'tag.sort' variable if it exists, or + lexicographic order otherwise. See linkgit:git-config[1]. --column[=<options>]:: --no-column:: @@ -317,6 +319,7 @@ include::date-formats.txt[] SEE ALSO -------- linkgit:git-check-ref-format[1]. +linkgit:git-config[1]. GIT --- diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index d6de4a0..dfc09d9 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -161,6 +161,17 @@ may not support it yet. Only meaningful with `--stdin` or `--index-info`; paths are separated with NUL character instead of LF. +--split-index:: +--no-split-index:: + Enable or disable split index mode. If enabled, the index is + split into two files, $GIT_DIR/index and $GIT_DIR/sharedindex.<SHA-1>. + Changes are accumulated in $GIT_DIR/index while the shared + index file contains all index entries stays unchanged. If + split-index mode is already enabled and `--split-index` is + given again, all changes in $GIT_DIR/index are pushed back to + the shared index file. This mode is designed for very large + indexes that take a signficant amount of time to read or write. + \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git.txt b/Documentation/git.txt index 7924209..05857c9 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.0.1/git.html[documentation for release 2.0.1] +* link:v2.0.2/git.html[documentation for release 2.0.2] * release notes for + link:RelNotes/2.0.2.txt[2.0.2], link:RelNotes/2.0.1.txt[2.0.1], link:RelNotes/2.0.0.txt[2.0.0]. @@ -905,31 +906,54 @@ for further details. based on whether stdout appears to be redirected to a file or not. 'GIT_TRACE':: - If this variable is set to "1", "2" or "true" (comparison - is case insensitive), Git will print `trace:` messages on - stderr telling about alias expansion, built-in command - execution and external command execution. - If this variable is set to an integer value greater than 1 - and lower than 10 (strictly) then Git will interpret this - value as an open file descriptor and will try to write the - trace messages into this file descriptor. - Alternatively, if this variable is set to an absolute path - (starting with a '/' character), Git will interpret this - as a file path and will try to write the trace messages - into it. + Enables general trace messages, e.g. alias expansion, built-in + command execution and external command execution. ++ +If this variable is set to "1", "2" or "true" (comparison +is case insensitive), trace messages will be printed to +stderr. ++ +If the variable is set to an integer value greater than 2 +and lower than 10 (strictly) then Git will interpret this +value as an open file descriptor and will try to write the +trace messages into this file descriptor. ++ +Alternatively, if the variable is set to an absolute path +(starting with a '/' character), Git will interpret this +as a file path and will try to write the trace messages +into it. ++ +Unsetting the variable, or setting it to empty, "0" or +"false" (case insensitive) disables trace messages. 'GIT_TRACE_PACK_ACCESS':: - If this variable is set to a path, a file will be created at - the given path logging all accesses to any packs. For each + Enables trace messages for all accesses to any packs. For each access, the pack file name and an offset in the pack is recorded. This may be helpful for troubleshooting some pack-related performance problems. + See 'GIT_TRACE' for available trace output options. 'GIT_TRACE_PACKET':: - If this variable is set, it shows a trace of all packets - coming in or out of a given program. This can help with - debugging object negotiation or other protocol issues. Tracing - is turned off at a packet starting with "PACK". + Enables trace messages for all packets coming in or out of a + given program. This can help with debugging object negotiation + or other protocol issues. Tracing is turned off at a packet + starting with "PACK". + See 'GIT_TRACE' for available trace output options. + +'GIT_TRACE_PERFORMANCE':: + Enables performance related trace messages, e.g. total execution + time of each Git command. + See 'GIT_TRACE' for available trace output options. + +'GIT_TRACE_SETUP':: + Enables trace messages printing the .git, working tree and current + working directory after Git has completed its setup phase. + See 'GIT_TRACE' for available trace output options. + +'GIT_TRACE_SHALLOW':: + Enables trace messages that can help debugging fetching / + cloning of shallow repositories. + See 'GIT_TRACE' for available trace output options. GIT_LITERAL_PATHSPECS:: Setting this variable to `1` will cause Git to treat all diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index 17d2ea6..79653f3 100644 --- a/Documentation/gitrepository-layout.txt +++ b/Documentation/gitrepository-layout.txt @@ -155,6 +155,10 @@ index:: The current index file for the repository. It is usually not found in a bare repository. +sharedindex.<SHA-1>:: + The shared index part, to be referenced by $GIT_DIR/index and + other temporary index files. Only valid in split index mode. + info:: Additional information about the repository is recorded in this directory. diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt index b977ae8..ad7a5bd 100644 --- a/Documentation/technical/api-hashmap.txt +++ b/Documentation/technical/api-hashmap.txt @@ -8,11 +8,19 @@ Data Structures `struct hashmap`:: - The hash table structure. + The hash table structure. Members can be used as follows, but should + not be modified directly: + -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. +The `size` member keeps track of the total number of entries (0 means the +hashmap is empty). ++ +`tablesize` is the allocated size of the hash table. A non-0 value indicates +that the hashmap is initialized. It may also be useful for statistical purposes +(i.e. `size / tablesize` is the current load factor). ++ +`cmpfn` stores the comparison function specified in `hashmap_init()`. In +advanced scenarios, it may be useful to change this, e.g. to switch between +case-sensitive and case-insensitive lookup. `struct hashmap_entry`:: @@ -58,6 +66,15 @@ Functions + `strihash` and `memihash` are case insensitive versions. +`unsigned int sha1hash(const unsigned char *sha1)`:: + + Converts a cryptographic hash (e.g. SHA-1) into an int-sized hash code + for use in hash tables. Cryptographic hashes are supposed to have + uniform distribution, so in contrast to `memhash()`, this just copies + the first `sizeof(int)` bytes without shuffling any bits. Note that + the results will be different on big-endian and little-endian + platforms, so they should not be stored or transferred over the net. + `void hashmap_init(struct hashmap *map, hashmap_cmp_fn equals_function, size_t initial_size)`:: Initializes a hashmap structure. @@ -101,6 +118,20 @@ hashmap_entry) that has at least been initialized with the proper hash code 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_from_hash(const struct hashmap *map, unsigned int hash, const void *keydata)`:: + + Returns the hashmap entry for the specified hash code and key data, + or NULL if not found. ++ +`map` is the hashmap structure. ++ +`hash` is the hash code of the entry to look up. ++ +If an entry with matching hash code is found, `keydata` is passed to +`hashmap_cmp_fn` to decide whether the entry matches the key. The +`entry_or_key` parameter points to a bogus hashmap_entry structure that +should not be used in the comparison. + `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 @@ -162,6 +193,21 @@ more entries. `hashmap_iter_first` is a combination of both (i.e. initializes the iterator and returns the first entry, if any). +`const char *strintern(const char *string)`:: +`const void *memintern(const void *data, size_t len)`:: + + Returns the unique, interned version of the specified string or data, + similar to the `String.intern` API in Java and .NET, respectively. + Interned strings remain valid for the entire lifetime of the process. ++ +Can be used as `[x]strdup()` or `xmemdupz` replacement, except that interned +strings / data must not be modified or freed. ++ +Interned strings are best used for short strings with high probability of +duplicates. ++ +Uses a hashmap to store the pool of interned strings. + Usage example ------------- diff --git a/Documentation/technical/api-trace.txt b/Documentation/technical/api-trace.txt new file mode 100644 index 0000000..097a651 --- /dev/null +++ b/Documentation/technical/api-trace.txt @@ -0,0 +1,97 @@ +trace API +========= + +The trace API can be used to print debug messages to stderr or a file. Trace +code is inactive unless explicitly enabled by setting `GIT_TRACE*` environment +variables. + +The trace implementation automatically adds `timestamp file:line ... \n` to +all trace messages. E.g.: + +------------ +23:59:59.123456 git.c:312 trace: built-in: git 'foo' +00:00:00.000001 builtin/foo.c:99 foo: some message +------------ + +Data Structures +--------------- + +`struct trace_key`:: + + Defines a trace key (or category). The default (for API functions that + don't take a key) is `GIT_TRACE`. ++ +E.g. to define a trace key controlled by environment variable `GIT_TRACE_FOO`: ++ +------------ +static struct trace_key trace_foo = TRACE_KEY_INIT(FOO); + +static void trace_print_foo(const char *message) +{ + trace_print_key(&trace_foo, message); +} +------------ ++ +Note: don't use `const` as the trace implementation stores internal state in +the `trace_key` structure. + +Functions +--------- + +`int trace_want(struct trace_key *key)`:: + + Checks whether the trace key is enabled. Used to prevent expensive + string formatting before calling one of the printing APIs. + +`void trace_disable(struct trace_key *key)`:: + + Disables tracing for the specified key, even if the environment + variable was set. + +`void trace_printf(const char *format, ...)`:: +`void trace_printf_key(struct trace_key *key, const char *format, ...)`:: + + Prints a formatted message, similar to printf. + +`void trace_argv_printf(const char **argv, const char *format, ...)``:: + + Prints a formatted message, followed by a quoted list of arguments. + +`void trace_strbuf(struct trace_key *key, const struct strbuf *data)`:: + + Prints the strbuf, without additional formatting (i.e. doesn't + choke on `%` or even `\0`). + +`uint64_t getnanotime(void)`:: + + Returns nanoseconds since the epoch (01/01/1970), typically used + for performance measurements. ++ +Currently there are high precision timer implementations for Linux (using +`clock_gettime(CLOCK_MONOTONIC)`) and Windows (`QueryPerformanceCounter`). +Other platforms use `gettimeofday` as time source. + +`void trace_performance(uint64_t nanos, const char *format, ...)`:: +`void trace_performance_since(uint64_t start, const char *format, ...)`:: + + Prints the elapsed time (in nanoseconds), or elapsed time since + `start`, followed by a formatted message. Enabled via environment + variable `GIT_TRACE_PERFORMANCE`. Used for manual profiling, e.g.: ++ +------------ +uint64_t start = getnanotime(); +/* code section to measure */ +trace_performance_since(start, "foobar"); +------------ ++ +------------ +uint64_t t = 0; +for (;;) { + /* ignore */ + t -= getnanotime(); + /* code section to measure */ + t += getnanotime(); + /* ignore */ +} +trace_performance(t, "frotz"); +------------ diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index f352a9b..fe6f316 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -129,6 +129,9 @@ Git index format (Version 4) In version 4, the padding after the pathname does not exist. + Interpretation of index entries in split index mode is completely + different. See below for details. + == Extensions === Cached tree @@ -198,3 +201,35 @@ Git index format - At most three 160-bit object names of the entry in stages from 1 to 3 (nothing is written for a missing stage). +=== Split index + + In split index mode, the majority of index entries could be stored + in a separate file. This extension records the changes to be made on + top of that to produce the final index. + + The signature for this extension is { 'l', 'i, 'n', 'k' }. + + The extension consists of: + + - 160-bit SHA-1 of the shared index file. The shared index file path + is $GIT_DIR/sharedindex.<SHA-1>. If all 160 bits are zero, the + index does not require a shared index file. + + - An ewah-encoded delete bitmap, each bit represents an entry in the + shared index. If a bit is set, its corresponding entry in the + shared index will be removed from the final index. Note, because + a delete operation changes index entry positions, but we do need + original positions in replace phase, it's best to just mark + entries for removal, then do a mass deletion after replacement. + + - An ewah-encoded replace bitmap, each bit represents an entry in + the shared index. If a bit is set, its corresponding entry in the + shared index will be replaced with an entry in this index + file. All replaced entries are stored in sorted order in this + index. The first "1" bit in the replace bitmap corresponds to the + first index entry, the second "1" bit to the second entry and so + on. Replaced entries may have empty path names to save space. + + The remaining index entries after replaced ones will be added to the + final index. These added entries are also sorted by entry namme then + stage. |