diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/CodingGuidelines | 9 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.0.2.txt | 32 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.0.3.txt | 17 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.0.4.txt | 5 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.1.0.txt | 180 | ||||
| -rw-r--r-- | Documentation/config.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-push.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-replace.txt | 18 | ||||
| -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-verify-commit.txt | 28 | ||||
| -rw-r--r-- | Documentation/git.txt | 71 | ||||
| -rw-r--r-- | Documentation/gitrepository-layout.txt | 4 | ||||
| -rw-r--r-- | Documentation/technical/api-config.txt | 31 | ||||
| -rw-r--r-- | Documentation/technical/api-hashmap.txt | 54 | ||||
| -rw-r--r-- | Documentation/technical/api-string-list.txt | 5 | ||||
| -rw-r--r-- | Documentation/technical/api-trace.txt | 97 | ||||
| -rw-r--r-- | Documentation/technical/index-format.txt | 35 |
19 files changed, 542 insertions, 73 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 4d90c77c7b..894546dd75 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 new file mode 100644 index 0000000000..8e8321b2ef --- /dev/null +++ b/Documentation/RelNotes/2.0.2.txt @@ -0,0 +1,32 @@ +Git v2.0.2 Release Notes +======================== + + * Documentation for "git submodule sync" forgot to say that the subcommand + can take the "--recursive" option. + + * Mishandling of patterns in .gitignore that has trailing SPs quoted + with backslashes (e.g. ones that end with "\ ") have been + corrected. + + * 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.0.3.txt b/Documentation/RelNotes/2.0.3.txt new file mode 100644 index 0000000000..4047b46bbe --- /dev/null +++ b/Documentation/RelNotes/2.0.3.txt @@ -0,0 +1,17 @@ +Git v2.0.3 Release Notes +======================== + + * An ancient rewrite passed a wrong pointer to a curl library + function in a rarely used code path. + + * "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". + + * "log --show-signature" incorrectly decided the color to paint a + mergetag that was and was not correctly validated. + + * "log --show-signature" did not pay attention to "--graph" option. + +Also a lot of fixes to the tests and some updates to the docs are +included. diff --git a/Documentation/RelNotes/2.0.4.txt b/Documentation/RelNotes/2.0.4.txt new file mode 100644 index 0000000000..7e340921a2 --- /dev/null +++ b/Documentation/RelNotes/2.0.4.txt @@ -0,0 +1,5 @@ +Git v2.0.4 Release Notes +======================== + + * An earlier update to v2.0.2 broken output from "git diff-tree", + which is fixed in this release. diff --git a/Documentation/RelNotes/2.1.0.txt b/Documentation/RelNotes/2.1.0.txt index 828a439dc1..ae4753728e 100644 --- a/Documentation/RelNotes/2.1.0.txt +++ b/Documentation/RelNotes/2.1.0.txt @@ -12,7 +12,7 @@ Backward compatibility notes $ git config core.pager "less -S" to restore the traditional behaviour. It is expected that people - find output from the most subcommands easier to read with the new + find output from most subcommands easier to read with the new default, except for "blame" which tends to produce really long lines. To override the new default only for "git blame", you can do this: @@ -31,7 +31,7 @@ UI, Workflows & Features default value "FRSX" when we spawn "less" as the pager. "S" (chop long lines instead of wrapping) has been removed from this default set of options, because it is more or less a personal taste thing, - as opposed to others that have good justifications (i.e. "R" is + as opposed to the others that have good justifications (i.e. "R" is very much justified because many kinds of output we produce are colored and "FX" is justified because output we produce is often shorter than a page). @@ -39,41 +39,47 @@ UI, Workflows & Features * The logic and data used to compute the display width needed for UTF-8 strings have been updated to match Unicode 7.0 better. - * HTTP-based transports learned to propagate the error messages from - the webserver better to the client coming over the HTTP transport. + * HTTP-based transports learned to better propagate the error messages from + the webserver to the client coming over the HTTP transport. * The completion script for bash (in contrib/) has been updated to - handle aliases that define complex sequence of commands better. + better handle aliases that define a complex sequence of commands. - * The "core.preloadindex" configuration variable is by default - enabled, allowing modern platforms to take advantage of the - multiple cores they have. + * The "core.preloadindex" configuration variable is enabled by default, + allowing modern platforms to take advantage of their + multiple cores. - * "git commit --date=<date>" option learned to read from more + * "git clone" applies the "if cloning from a local disk, physically + copy the repository using hardlinks, unless otherwise told not to with + --no-local" optimization when the url.*.insteadOf mechanism rewrites a + remote-repository "git clone $URL" into a + clone from a local disk. + + * "git commit --date=<date>" option learned more timestamp formats, including "--date=now". * The `core.commentChar` configuration variable is used to specify a - custom comment character other than the default "#" to be used in - the commit log editor. This can be set to `auto` to attempt to - choose a different character that does not conflict with what - already starts a line in the message being edited for cases like + custom comment character (other than the default "#") for + the commit message editor. This can be set to `auto` to attempt to + choose a different character that does not conflict with any that + already starts a line in the message being edited, for cases like "git commit --amend". - * "git format-patch" learned --signature-file=<file> to take the mail - signature from. + * "git format-patch" learned --signature-file=<file> to add the contents + of a file as a signature to the mail message it produces. - * "git grep" learned grep.fullname configuration variable to force - "--full-name" to be default. This may cause regressions on - scripted users that do not expect this new behaviour. + * "git grep" learned the grep.fullname configuration variable to force + "--full-name" to be the default. This may cause regressions for + scripted users who do not expect this new behaviour. * "git imap-send" learned to ask the credential helper for auth material. - * "git log" and friends now understand the value "auto" set to the + * "git log" and friends now understand the value "auto" for the "log.decorate" configuration variable to enable the "--decorate" option automatically when the output is sent to tty. - * "git merge" without argument, even when there is an upstream + * "git merge" without an argument, even when there is an upstream defined for the current branch, refused to run until merge.defaultToUpstream is set to true. Flip the default of that configuration variable to true. @@ -81,19 +87,21 @@ UI, Workflows & Features * "git mergetool" learned to drive the vimdiff3 backend. * mergetool.prompt used to default to 'true', always asking "do you - really want to run the tool on this path?". Among the two - purposes this prompt serves, ignore the use case to confirm that - the user wants to view particular path with the named tool, and - redefine the meaning of the prompt only to confirm the choice of - the tool made by the autodetection (for those who configured the - tool explicitly, the prompt shown for the latter purpose is - simply annoying). - - Strictly speaking, this is a backward incompatible change and the + really want to run the tool on this path?". The default has been + changed to 'false'. However, the prompt will still appear if + mergetool used its autodetection system to guess which tool to use. + Users who explicitly specify or configure a tool will no longer see + the prompt by default. + + Strictly speaking, this is a backward incompatible change and users need to explicitly set the variable to 'true' if they want - to resurrect the now-ignored use case. + to be prompted to confirm running the tool on each path. + + * "git replace" learned the "--edit" subcommand to create a + replacement by editing an existing object. - * "git replace" learned the "--edit" subcommand. + * "git replace" learned a "--graft" option to rewrite the parents of a + commit. * "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 @@ -106,11 +114,35 @@ UI, Workflows & Features * "git tag" when editing the tag message shows the name of the tag being edited as a comment in the editor. + * "git tag" learned to pay attention to "tag.sort" configuration, to + be used as the default sort order when no --sort=<value> option + is given. + + * A new "git verify-commit" command, to check GPG signatures in signed + commits, in a way similar to "git verify-tag" is used to check + signed tags, was added. + Performance, Internal Implementation, etc. * Build procedure for 'subtree' (in contrib/) has been cleaned up. + * Support for the profile-feedback build, which has + bit-rotted 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. More tests that are not applicable + to the Windows environment are identified and either skipped or + made more portable. + + * Eradication of "test $condition -a $condition" from our scripts + continues. + * The `core.deltabasecachelimit` used to default to 16 MiB , but this proved to be too small, and has been bumped to 96 MiB. @@ -118,13 +150,16 @@ Performance, Internal Implementation, etc. structure that is used to keep track of the work to be done. * "git diff" that compares 3-or-more trees (e.g. parents and the - result of a merge) have been optimized. + result of a merge) has been optimized. * The API to update/delete references are being converted to handle updates to multiple references in a transactional way. As an 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. @@ -151,8 +186,8 @@ notes for details). to a tty. (merge 38de156 mn/sideband-no-ansi later to maint). - * Mishandling of patterns in .gitignore that has trailing SPs quoted - with backslashes (e.g. ones that end with "\ ") have been + * Mishandling of patterns in .gitignore that have trailing SPs quoted + with backslashes (e.g. ones that end with "\ ") has been corrected. (merge 97c1364be6b pb/trim-trailing-spaces later to maint). @@ -166,6 +201,11 @@ notes for details). be checked out currently. (merge e3fa568 jc/revision-dash-count-parsing later to maint). + * 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 in the example) with padding to column-align the output, but did @@ -173,7 +213,18 @@ notes for details). columns are different. (merge 7d50987 as/pretty-truncate later to maint). - * The "mailmap.file" configuration option did not support the tilde + * "%G" (nothing after G) is an invalid pretty format specifier, but + the parser did not notice it as garbage. + (merge 958b2eb jk/pretty-G-format-fixes later to maint). + + * 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. + (merge 218aa3a jk/commit-buffer-length later to maint). + + * The "mailmap.file" configuration option did not support tilde expansion (i.e. ~user/path and ~/path). (merge 9352fd5 ow/config-mailmap-pathname later to maint). @@ -182,13 +233,23 @@ notes for details). couple of options unique to "git merge". (merge 8fee872 jk/complete-merge-pull later to maint). + * The unix-domain socket used by the sample credential cache daemon + tried to unlink an existing stale one at a wrong path, if the path + to the socket was given as an overlong path that does not fit in + the sun_path member of the sockaddr_un structure. + (merge 2869b3e rs/fix-unlink-unix-socket 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. + at the beginning of lines too aggressively, which is inconsistent + with the option of the same name that "diff" and "git diff" have. (merge 14d3bb4 jc/apply-ignore-whitespace later to maint). - * "git blame" miscounted number of columns needed to show localized - timestamps, resulting in jaggy left-side-edge of the source code + * "git blame" miscounted the number of columns needed to show localized + timestamps, resulting in a jaggy left-side-edge for the source code lines in its output. (merge dd75553 jx/blame-align-relative-time later to maint). @@ -197,15 +258,25 @@ notes for details). line endings. (merge 4d4813a bc/blame-crlf-test later to maint). - * "git commit --allow-empty-messag -C $commit" did not work when the + * "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(). + (merge 60a5f5f jc/fix-clone-single-starting-at-a-tag later to maint). + + * "git commit --allow-empty-message -C $commit" did not work when the commit did not have any log message. (merge 076cbd6 jk/commit-C-pick-empty later to maint). * "git diff --find-copies-harder" sometimes pretended as if the mode - bits have changed for paths that are marked with assume-unchanged + bits have changed for paths that are marked with the assume-unchanged 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 get 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. @@ -231,7 +302,14 @@ notes for details). distinguish missing objects from type errors. (merge 77583e7 jk/index-pack-report-missing later to maint). - * "git mailinfo" used to read beyond the end of header string while + * "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 the "--graph" option. + (merge cf3983d zk/log-graph-showsig later to maint). + + * "git mailinfo" used to read beyond the ends of header strings while parsing an incoming e-mail message to extract the patch. (merge b1a013d rs/mailinfo-header-cmp later to maint). @@ -240,13 +318,18 @@ 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. (merge fb79947 rs/pack-objects-no-unnecessary-realloc later to maint). * Recent updates to "git repack" started to duplicate objects that - are in packfiles marked with .keep flag into the new packfile by + are in packfiles marked with the .keep flag into the new packfile by mistake. (merge d078d85 jk/repack-pack-keep-objects later to maint). @@ -270,6 +353,13 @@ notes for details). emptying the insn sheet. (merge ddb5432 rr/rebase-autostash-fix later to maint). + * "git rebase --fork-point" did not filter out patch-identical + commits correctly. + + * During "git rebase --merge", a conflicted patch could not be + skipped with "--skip" if the next one also conflicted. + (merge 95104c7 bc/fix-rebase-merge-skip later to maint). + * "git show -s" (i.e. show log message only) used to incorrectly emit an extra blank line after a merge commit. (merge ad2f725 mk/show-s-no-extra-blank-line-for-merges later to maint). @@ -277,14 +367,14 @@ notes for details). * "git status", even though it is a read-only operation, tries to update the index with refreshed lstat(2) info to optimize future accesses to the working tree opportunistically, but this could - race with a "read-write" operation that modify the index while it + race with a "read-write" operation that modifies the index while it is running. Detect such a race and avoid overwriting the index. (merge 426ddee ym/fix-opportunistic-index-update-race later to maint). * "git status" (and "git commit") behaved as if changes in a modified submodule are not there if submodule.*.ignore configuration is set, which was misleading. The configuration is only to unclutter diff - output during the course of development, and should not to hide + output during the course of development, and not to hide changes in the "status" output to cause the users forget to commit them. (merge c215d3d jl/status-added-submodule-is-never-ignored later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index 1d718bdb96..c55c22ab7b 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-push.txt b/Documentation/git-push.txt index 21cd455508..c0d7403b9a 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -33,7 +33,7 @@ When the command line does not specify what to push with `<refspec>...` arguments or `--all`, `--mirror`, `--tags` options, the command finds the default `<refspec>` by consulting `remote.*.push` configuration, and if it is not found, honors `push.default` configuration to decide -what to push (See gitlink:git-config[1] for the meaning of `push.default`). +what to push (See linkgit:git-config[1] for the meaning of `push.default`). OPTIONS[[OPTIONS]] diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 61461b9f33..8fff598fd6 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -10,6 +10,7 @@ SYNOPSIS [verse] 'git replace' [-f] <object> <replacement> 'git replace' [-f] --edit <object> +'git replace' [-f] --graft <commit> [<parent>...] 'git replace' -d <object>... 'git replace' [--format=<format>] [-l [<pattern>]] @@ -73,6 +74,23 @@ 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. + +--graft <commit> [<parent>...]:: + Create a graft commit. A new commit is created with the same + content as <commit> except that its parents will be + [<parent>...] instead of <commit>'s parents. A replacement ref + is then created to replace <commit> with the newly created + commit. See contrib/convert-grafts-to-replace-refs.sh for an + example script based on this option that can convert grafts to + replace refs. + -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 987395d22a..0b84769bd9 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 b424a1bc48..320908369f 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 d6de4a008c..dfc09d93d8 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-verify-commit.txt b/Documentation/git-verify-commit.txt new file mode 100644 index 0000000000..9413e2802a --- /dev/null +++ b/Documentation/git-verify-commit.txt @@ -0,0 +1,28 @@ +git-verify-commit(1) +==================== + +NAME +---- +git-verify-commit - Check the GPG signature of commits + +SYNOPSIS +-------- +[verse] +'git verify-commit' <commit>... + +DESCRIPTION +----------- +Validates the gpg signature created by 'git commit -S'. + +OPTIONS +------- +-v:: +--verbose:: + Print the contents of the commit object before validating it. + +<commit>...:: + SHA-1 identifiers of Git commit objects. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git.txt b/Documentation/git.txt index 7924209671..de7b870a35 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,17 @@ 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.1.0/git.html[documentation for release 2.1] * release notes for + link:RelNotes/2.1.0.txt[2.1]. + +* link:v2.0.4/git.html[documentation for release 2.0.4] + +* release notes for + link:RelNotes/2.0.4.txt[2.0.4], + link:RelNotes/2.0.3.txt[2.0.3], + 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 +913,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 @@ -1043,7 +1074,7 @@ Authors ------- Git was started by Linus Torvalds, and is currently maintained by Junio C Hamano. Numerous contributions have come from the Git mailing list -<git@vger.kernel.org>. http://www.ohloh.net/p/git/contributors/summary +<git@vger.kernel.org>. http://www.openhub.net/p/git/contributors/summary gives you a more complete list of contributors. If you have a clone of git.git itself, the diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt index 17d2ea6c1e..79653f3134 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-config.txt b/Documentation/technical/api-config.txt index 230b3a0f60..edd5018e15 100644 --- a/Documentation/technical/api-config.txt +++ b/Documentation/technical/api-config.txt @@ -137,4 +137,33 @@ int read_file_with_include(const char *file, config_fn_t fn, void *data) Writing Config Files -------------------- -TODO +Git gives multiple entry points in the Config API to write config values to +files namely `git_config_set_in_file` and `git_config_set`, which write to +a specific config file or to `.git/config` respectively. They both take a +key/value pair as parameter. +In the end they both call `git_config_set_multivar_in_file` which takes four +parameters: + +- the name of the file, as a string, to which key/value pairs will be written. + +- the name of key, as a string. This is in canonical "flat" form: the section, + subsection, and variable segments will be separated by dots, and the section + and variable segments will be all lowercase. + E.g., `core.ignorecase`, `diff.SomeType.textconv`. + +- the value of the variable, as a string. If value is equal to NULL, it will + remove the matching key from the config file. + +- the value regex, as a string. It will disregard key/value pairs where value + does not match. + +- a multi_replace value, as an int. If value is equal to zero, nothing or only + one matching key/value is replaced, else all matching key/values (regardless + how many) are removed, before the new pair is written. + +It returns 0 on success. + +Also, there are functions `git_config_rename_section` and +`git_config_rename_section_in_file` with parameters `old_name` and `new_name` +for renaming or removing sections in the config files. If NULL is passed +through `new_name` parameter, the section will be removed from the config file. diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt index b977ae8bbb..ad7a5bddd2 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-string-list.txt b/Documentation/technical/api-string-list.txt index f1add51efe..d51a6579c8 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -68,6 +68,11 @@ Functions * General ones (works with sorted and unsorted lists as well) +`string_list_init`:: + + Initialize the members of the string_list, set `strdup_strings` + member according to the value of the second parameter. + `filter_string_list`:: Apply a function to each item in a list, retaining only the diff --git a/Documentation/technical/api-trace.txt b/Documentation/technical/api-trace.txt new file mode 100644 index 0000000000..097a651d96 --- /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 f352a9b22e..fe6f31667d 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. |