diff options
Diffstat (limited to 'Documentation')
35 files changed, 449 insertions, 175 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 80d1908a44..b980407059 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -272,7 +272,9 @@ install-html: html ../GIT-VERSION-FILE: FORCE $(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE +ifneq ($(MAKECMDGOALS),clean) -include ../GIT-VERSION-FILE +endif # # Determine "include::" file references in asciidoc files. @@ -286,7 +288,9 @@ doc.dep : $(docdep_prereqs) $(wildcard *.txt) $(wildcard config/*.txt) build-doc $(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \ mv $@+ $@ +ifneq ($(MAKECMDGOALS),clean) -include doc.dep +endif cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-ancillarymanipulators.txt \ @@ -380,7 +384,10 @@ SubmittingPatches.txt: SubmittingPatches $(QUIET_GEN) cp $< $@ XSLT = docbook.xsl -XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css +XSLTOPTS = +XSLTOPTS += --xinclude +XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css +XSLTOPTS += --param generate.consistent.ids 1 user-manual.html: user-manual.xml $(XSLT) $(QUIET_XSLTPROC)$(RM) $@+ $@ && \ diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 60eed5edcd..7c9a037cc2 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -1143,11 +1143,25 @@ After a few days, you will hopefully receive a reply to your patchset with some comments. Woohoo! Now you can get back to work. It's good manners to reply to each comment, notifying the reviewer that you have -made the change requested, feel the original is better, or that the comment +made the change suggested, feel the original is better, or that the comment inspired you to do something a new way which is superior to both the original and the suggested change. This way reviewers don't need to inspect your v2 to figure out whether you implemented their comment or not. +Reviewers may ask you about what you wrote in the patchset, either in +the proposed commit log message or in the changes themselves. You +should answer these questions in your response messages, but often the +reason why reviewers asked these questions to understand what you meant +to write is because your patchset needed clarification to be understood. + +Do not be satisfied by just answering their questions in your response +and hear them say that they now understand what you wanted to say. +Update your patches to clarify the points reviewers had trouble with, +and prepare your v2; the words you used to explain your v1 to answer +reviewers' questions may be useful thing to use. Your goal is to make +your v2 clear enough so that it becomes unnecessary for you to give the +same explanation to the next person who reads it. + If you are going to push back on a comment, be polite and explain why you feel your original is better; be prepared that the reviewer may still disagree with you, and the rest of the community may weigh in on one side or the other. As diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt index c3f2d1a831..2d10eea7a9 100644 --- a/Documentation/MyFirstObjectWalk.txt +++ b/Documentation/MyFirstObjectWalk.txt @@ -182,30 +182,6 @@ its `init_log_defaults()` sets its own state (`decoration_style`) and asks `grep` and `diff` to initialize themselves by calling each of their initialization functions. -For our first example within `git walken`, we don't intend to use any other -components within Git, and we don't have any configuration to do. However, we -may want to add some later, so for now, we can add an empty placeholder. Create -a new function in `builtin/walken.c`: - ----- -static void init_walken_defaults(void) -{ - /* - * We don't actually need the same components `git log` does; leave this - * empty for now. - */ -} ----- - -Make sure to add a line invoking it inside of `cmd_walken()`. - ----- -int cmd_walken(int argc, const char **argv, const char *prefix) -{ - init_walken_defaults(); -} ----- - ==== Configuring From `.gitconfig` Next, we should have a look at any relevant configuration settings (i.e., @@ -388,17 +364,9 @@ Next, let's try to filter the commits we see based on their author. This is equivalent to running `git log --author=<pattern>`. We can add a filter by modifying `rev_info.grep_filter`, which is a `struct grep_opt`. -First some setup. Add `init_grep_defaults()` to `init_walken_defaults()` and add -`grep_config()` to `git_walken_config()`: +First some setup. Add `grep_config()` to `git_walken_config()`: ---- -static void init_walken_defaults(void) -{ - init_grep_defaults(the_repository); -} - -... - static int git_walken_config(const char *var, const char *value, void *cb) { grep_config(var, value, cb); diff --git a/Documentation/RelNotes/2.30.0.txt b/Documentation/RelNotes/2.30.0.txt index 0933a7f84f..c2f1dc7b06 100644 --- a/Documentation/RelNotes/2.30.0.txt +++ b/Documentation/RelNotes/2.30.0.txt @@ -68,6 +68,41 @@ UI, Workflows & Features * Zsh autocompletion (in contrib/) update. + * The maximum length of output filenames "git format-patch" creates + has become configurable (used to be capped at 64). + + * "git rev-parse" learned the "--end-of-options" to help scripts to + safely take a parameter that is supposed to be a revision, e.g. + "git rev-parse --verify -q --end-of-options $rev". + + * The command line completion script (in contrib/) learned to expand + commands that are alias of alias. + + * "git update-ref --stdin" learns to take multiple transactions in a + single session. + + * Various subcommands of "git config" that take value_regex + learned the "--literal-value" option to take the value_regex option + as a literal string. + + * The transport layer was taught to optionally exchange the session + ID assigned by the trace2 subsystem during fetch/push transactions. + + * "git imap-send" used to ignore configuration variables like + core.askpass; this has been corrected. + + * "git $cmd $args", when $cmd is not a recognised subcommand, by + default tries to see if $cmd is a typo of an existing subcommand + and optionally executes the corrected command if there is only one + possibility, depending on the setting of help.autocorrect; the + users can now disable the whole thing, including the cycles spent + to find a likely typo, by setting the configuration variable to + 'never'. + + * "@" sometimes worked (e.g. "git push origin @:there") as a part of + a refspec element, but "git push origin @" did not work, which has + been corrected. + Performance, Internal Implementation, Development Support etc. @@ -85,11 +120,11 @@ Performance, Internal Implementation, Development Support etc. test pieces to run. * Adjust tests so that they won't scream when the default initial - branch name is changed to 'main'. + branch name is different from 'master'. * Rewriting "git bisect" in C continues. - * More preliminary tests have been added to document desired outcome + * More preliminary tests have been added to document desired outcomes of various "directory rename" situations. * Micro clean-up of a couple of test scripts. @@ -101,12 +136,38 @@ Performance, Internal Implementation, Development Support etc. * The code to detect premature EOF in the sideband demultiplexer has been cleaned up. - * Test scripts are being prepared to transition of the default branch - name to 'main'. - * "git fetch --depth=<n>" over the stateless RPC / smart HTTP transport handled EOF from the client poorly at the server end. + * A specialization of hashmap that uses a string as key has been + introduced. Hopefully it will see wider use over time. + + * "git bisect start/next" in a large span of history spends a lot of + time trying to come up with exactly the half-way point; this can be + optimized by stopping when we see a commit that is close enough to + the half-way point. + + * A lazily defined test prerequisite can now be defined in terms of + another lazily defined test prerequisite. + + * Expectation for the original contributor after responding to a + review comment to use the explanation in a patch update has been + described. + + * Multiple "credential-store" backends can race to lock the same + file, causing everybody else but one to fail---reattempt locking + with some timeout to reduce the rate of the failure. + + * "git-parse-remote" shell script library outlived its usefulness. + + * Like die() and error(), a call to warning() will also trigger a + trace2 event. + + * Use of non-reentrant localtime() has been removed. + + * Non-reentrant time-related library functions and ctime/asctime with + awkward calling interfaces are banned from the codebase. + Fixes since v2.29 ----------------- @@ -188,7 +249,7 @@ Fixes since v2.29 (merge c779386182 jc/sequencer-stopped-sha-simplify later to maint). * The code to see if "git stash drop" can safely remove refs/stash - has been made more carerful. + has been made more careful. (merge 4f44c5659b rs/empty-reflog-check-fix later to maint). * "git log -L<range>:<path>" is documented to take no pathspec, but @@ -217,6 +278,92 @@ Fixes since v2.29 non-existent object name in the input, instead of complaining. (merge c714d05875 jc/blame-ignore-fix later to maint). + * Running "git diff" while allowing external diff in a state with + unmerged paths used to segfault, which has been corrected. + (merge d66851806f jk/diff-release-filespec-fix later to maint). + + * Build configuration cleanup. + (merge b990f02fd8 ab/config-mak-uname-simplify later to maint). + + * Fix regression introduced when nvimdiff support in mergetool was added. + (merge 12026f46e7 pd/mergetool-nvimdiff later to maint). + + * The exchange between receive-pack and proc-receive hook did not + carefully check for errors. + + * The code was not prepared to deal with pack .idx file that is + larger than 4GB. + (merge 81c4c5cf2e jk/4gb-idx later to maint). + + * Since jgit does not yet work with SHA-256 repositories, mark the + tests that use it not to run unless we are testing with ShA-1 + repositories. + (merge ea699b4adc sg/t5310-jgit-wants-sha1 later to maint). + + * Config parser fix for "git notes". + (merge 45fef1599a na/notes-displayref-is-not-boolean later to maint). + + * Move a definition of compatibility wrapper from cache.h to + git-compat-util.h + (merge a76b138daa hn/sleep-millisec-decl later to maint). + + * Error message fix. + (merge eaf5341538 km/stash-error-message-fix later to maint). + + * "git pull --rebase --recurse-submodules" checked for local changes + in a wrong range and failed to run correctly when it should. + (merge 5176f20ffe pb/pull-rebase-recurse-submodules later to maint). + + * "git push" that is killed may leave a pack-objects process behind, + still computing to find a good compression, wasting cycles. This + has been corrected. + (merge 8b59935114 jk/stop-pack-objects-when-push-is-killed later to maint). + + * "git fetch" that is killed may leave a pack-objects process behind, + still computing to find a good compression, wasting cycles. This + has been corrected. + (merge 309a4028e7 jk/stop-pack-objects-when-fetch-is-killed later to maint). + + * "git add -i" failed to honor custom colors configured to show + patches, which has been corrected. + (merge 96386faa03 js/add-i-color-fix later to maint). + + * Processes that access packdata while the .idx file gets removed + (e.g. while repacking) did not fail or fall back gracefully as they + could. + (merge 506ec2fbda tb/idx-midx-race-fix later to maint). + + * "git apply" adjusted the permission bits of working-tree files and + directories according to core.sharedRepository setting by mistake and + for a long time, which has been corrected. + (merge eb3c027e17 mt/do-not-use-scld-in-working-tree later to maint). + + * "fetch-pack" could pass NULL pointer to unlink(2) when it sees an + invalid filename; the error checking has been tightened to make + this impossible. + (merge 6031af387e rs/fetch-pack-invalid-lockfile later to maint). + + * "git maintenance run/start/stop" needed to be run in a repository + to hold the lockfile they use, but didn't make sure they are + actually in a repository, which has been corrected. + + * The glossary described a branch as an "active" line of development, + which is misleading---a stale and non-moving branch is still a + branch. + (merge eef1ceabd8 so/glossary-branch-is-not-necessarily-active later to maint). + + * Newer versions of xsltproc can assign IDs in HTML documents it + generates in a consistent manner. Use the feature to help format + HTML version of the user manual reproducibly. + (merge 3569e11d69 ae/doc-reproducible-html later to maint). + + * Tighten error checking in the codepath that responds to "git fetch". + (merge d43a21bdbb jk/check-config-parsing-error-in-upload-pack later to maint). + + * "git pack-redundant" when there is only one packfile used to crash, + which has been corrected. + (merge 0696232390 jx/pack-redundant-on-single-pack later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 3e0a5dc9af cc/doc-filter-branch-typofix later to maint). (merge 32c83afc2c cw/ci-ghwf-check-ws-errors later to maint). @@ -234,3 +381,21 @@ Fixes since v2.29 (merge b7e20b4373 mc/typofix later to maint). (merge f6bcd9a8a4 js/test-whitespace-fixes later to maint). (merge 53b67a801b js/test-file-size later to maint). + (merge 970909c2a7 rs/hashwrite-be64 later to maint). + (merge 5a923bb1f0 ma/list-object-filter-opt-msgfix later to maint). + (merge 1c3e412916 rs/archive-plug-leak-refname later to maint). + (merge d44e5267ea rs/plug-diff-cache-leak later to maint). + (merge 793c1464d3 ab/gc-keep-base-option later to maint). + (merge b86339b12b mt/worktree-error-message-fix later to maint). + (merge e01ae2a4a7 js/pull-rebase-use-advise later to maint). + (merge e63d774242 sn/config-doc-typofix later to maint). + (merge 08e9df2395 jk/multi-line-indent-style-fix later to maint). + (merge e66590348a da/vs-build-iconv-fix later to maint). + (merge 7fe07275be js/cmake-extra-built-ins-fix later to maint). + (merge 633eebe142 jb/midx-doc-update later to maint). + (merge 5885367e8f jh/index-v2-doc-on-fsmn later to maint). + (merge 14639a4779 jc/compat-util-setitimer-fix later to maint). + (merge 56f56ac50b ab/unreachable-break later to maint). + (merge 731d578b4f rb/nonstop-config-mak-uname-update later to maint). + (merge f4698738f9 es/perf-export-fix later to maint). + (merge 773c694142 nk/refspecs-negative-fix later to maint). diff --git a/Documentation/RelNotes/2.31.0.txt b/Documentation/RelNotes/2.31.0.txt new file mode 100644 index 0000000000..6bde597b2d --- /dev/null +++ b/Documentation/RelNotes/2.31.0.txt @@ -0,0 +1,32 @@ +Git 2.31 Release Notes +====================== + +Updates since v2.30 +------------------- + +UI, Workflows & Features + + * The "--format=%(trailers)" mechanism gets enhanced to make it + easier to design output for machine consumption. + + * When a user does not tell "git pull" to use rebase or merge, the + command gives a loud message telling a user to choose between + rebase or merge but creates a merge anyway, forcing users who would + want to rebase to redo the operation. Fix an early part of this + problem by tightening the condition to give the message---there is + no reason to stop or force the user to choose between rebase or + merge if the history fast-forwards. + + +Performance, Internal Implementation, Development Support etc. + + * A 3-year old test that was not testing anything useful has been + corrected. + + +Fixes since v2.30 +----------------- + + * Other code cleanup, docfix, build fix, etc. + (merge 505a276596 pk/subsub-fetch-fix-take-2 later to maint). + (merge 33fc56253b fc/t6030-bisect-reset-removes-auxiliary-files later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index f292c2689e..6ba50b1104 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -64,7 +64,7 @@ The variable names are case-insensitive, allow only alphanumeric characters and `-`, and must start with an alphabetic character. A line that defines a value can be continued to the next line by -ending it with a `\`; the backquote and the end-of-line are +ending it with a `\`; the backslash and the end-of-line are stripped. Leading whitespaces after 'name =', the remainder of the line after the first comment character '#' or ';', and trailing whitespaces of the line are discarded unless they are enclosed in diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 160aacad84..c04f62a54a 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -625,4 +625,6 @@ core.abbrev:: computed based on the approximate number of packed objects in your repository, which hopefully is enough for abbreviated object names to stay unique for some time. + If set to "no", no abbreviation is made and the object names + are shown in their full length. The minimum length is 4. diff --git a/Documentation/config/credential.txt b/Documentation/config/credential.txt index 9d01641c28..512f31876e 100644 --- a/Documentation/config/credential.txt +++ b/Documentation/config/credential.txt @@ -28,3 +28,9 @@ credential.<url>.*:: credentialCache.ignoreSIGHUP:: Tell git-credential-cache--daemon to ignore SIGHUP, instead of quitting. + +credentialStore.lockTimeoutMS:: + The length of time, in milliseconds, for git-credential-store to retry + when trying to lock the credentials file. Value 0 means not to retry at + all; -1 means to try indefinitely. Default is 1000 (i.e., retry for + 1s). diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt index 851bf410a3..fdbc06a4d2 100644 --- a/Documentation/config/format.txt +++ b/Documentation/config/format.txt @@ -94,6 +94,11 @@ format.outputDirectory:: Set a custom directory to store the resulting files instead of the current working directory. All directory components will be created. +format.filenameMaxLength:: + The maximum length of the output filenames generated by the + `format-patch` command; defaults to 64. Can be overridden + by the `--filename-max-length=<n>` command line option. + format.useAutoBase:: A boolean value which lets you enable the `--base=auto` option of format-patch by default. Can also be set to "whenAble" to allow diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index 00ea0a678e..c834e07991 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -44,9 +44,9 @@ gc.autoDetach:: gc.bigPackThreshold:: If non-zero, all packs larger than this limit are kept when - `git gc` is run. This is very similar to `--keep-base-pack` + `git gc` is run. This is very similar to `--keep-largest-pack` except that all packs that meet the threshold are kept, not - just the base pack. Defaults to zero. Common unit suffixes of + just the largest pack. Defaults to zero. Common unit suffixes of 'k', 'm', or 'g' are supported. + Note that if the number of kept packs is more than gc.autoPackLimit, @@ -57,7 +57,7 @@ gc.autoPackLimit and gc.bigPackThreshold should be respected again. If the amount of memory estimated for `git repack` to run smoothly is not available and `gc.bigPackThreshold` is not set, the largest pack will also be excluded (this is the equivalent of running `git gc` with -`--keep-base-pack`). +`--keep-largest-pack`). gc.writeCommitGraph:: If true, then gc will rewrite the commit-graph file when diff --git a/Documentation/config/help.txt b/Documentation/config/help.txt index 224bbf5a28..783a90a0f9 100644 --- a/Documentation/config/help.txt +++ b/Documentation/config/help.txt @@ -8,13 +8,14 @@ help.format:: the default. 'web' and 'html' are the same. help.autoCorrect:: - Automatically correct and execute mistyped commands after - waiting for the given number of deciseconds (0.1 sec). If more - than one command can be deduced from the entered text, nothing - will be executed. If the value of this option is negative, - the corrected command will be executed immediately. If the - value is 0 - the command will be just shown but not executed. - This is the default. + If git detects typos and can identify exactly one valid command similar + to the error, git will automatically run the intended command after + waiting a duration of time defined by this configuration value in + deciseconds (0.1 sec). If this value is 0, the suggested corrections + will be shown, but not executed. If it is a negative integer, or + "immediate", the suggested command + is run immediately. If "never", suggestions are not shown at all. The + default value is zero. help.htmlPath:: Specify the path where the HTML documentation resides. File system paths diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index 3968fbb697..7003661c0d 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -42,12 +42,12 @@ http.proxySSLKey:: http.proxySSLCertPasswordProtected:: Enable Git's password prompt for the proxy SSL certificate. Otherwise OpenSSL will prompt the user, possibly many times, if the certificate or private key - is encrypted. Can be overriden by the `GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED` + is encrypted. Can be overridden by the `GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED` environment variable. http.proxySSLCAInfo:: Pathname to the file containing the certificate bundle that should be used to - verify the proxy with when using an HTTPS proxy. Can be overriden by the + verify the proxy with when using an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_CAINFO` environment variable. http.emptyAuth:: diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt index 01d3afd8a8..fe1642f0d4 100644 --- a/Documentation/config/trace2.txt +++ b/Documentation/config/trace2.txt @@ -54,7 +54,7 @@ trace2.envVars:: `GIT_HTTP_USER_AGENT,GIT_CONFIG` would cause the trace2 output to contain events listing the overrides for HTTP user agent and the location of the Git configuration file (assuming any are set). May be - overriden by the `GIT_TRACE2_ENV_VARS` environment variable. Unset by + overridden by the `GIT_TRACE2_ENV_VARS` environment variable. Unset by default. trace2.destinationDebug:: diff --git a/Documentation/config/transfer.txt b/Documentation/config/transfer.txt index f5b6245270..505126a780 100644 --- a/Documentation/config/transfer.txt +++ b/Documentation/config/transfer.txt @@ -69,3 +69,7 @@ transfer.unpackLimit:: When `fetch.unpackLimit` or `receive.unpackLimit` are not set, the value of this variable is used instead. The default value is 100. + +transfer.advertiseSID:: + Boolean. When true, client and server processes will advertise their + unique session IDs to their remote counterpart. Defaults to false. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 7573160f21..0e9351d3cb 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,15 +9,15 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] name [value [value_regex]] +'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]] 'git config' [<file-option>] [--type=<type>] --add name value -'git config' [<file-option>] [--type=<type>] --replace-all name value [value_regex] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get name [value_regex] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get-all name [value_regex] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] +'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern] +'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern] 'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL -'git config' [<file-option>] --unset name [value_regex] -'git config' [<file-option>] --unset-all name [value_regex] +'git config' [<file-option>] [--fixed-value] --unset name [value-pattern] +'git config' [<file-option>] [--fixed-value] --unset-all name [value-pattern] 'git config' [<file-option>] --rename-section old_name new_name 'git config' [<file-option>] --remove-section name 'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list @@ -33,10 +33,13 @@ escaped. Multiple lines can be added to an option by using the `--add` option. If you want to update or unset an option which can occur on multiple -lines, a POSIX regexp `value_regex` needs to be given. Only the -existing values that match the regexp are updated or unset. If -you want to handle the lines that do *not* match the regex, just -prepend a single exclamation mark in front (see also <<EXAMPLES>>). +lines, a `value-pattern` (which is an extended regular expression, +unless the `--fixed-value` option is given) needs to be given. Only the +existing values that match the pattern are updated or unset. If +you want to handle the lines that do *not* match the pattern, just +prepend a single exclamation mark in front (see also <<EXAMPLES>>), +but note that this only works when the `--fixed-value` option is not +in use. The `--type=<type>` option instructs 'git config' to ensure that incoming and outgoing values are canonicalize-able under the given <type>. If no @@ -73,11 +76,11 @@ OPTIONS --replace-all:: Default behavior is to replace at most one line. This replaces - all lines matching the key (and optionally the value_regex). + all lines matching the key (and optionally the `value-pattern`). --add:: Adds a new line to the option without altering any existing - values. This is the same as providing '^$' as the value_regex + values. This is the same as providing '^$' as the `value-pattern` in `--replace-all`. --get:: @@ -165,6 +168,12 @@ See also <<FILES>>. --list:: List all variables set in config file, along with their values. +--fixed-value:: + When used with the `value-pattern` argument, treat `value-pattern` as + an exact string instead of a regular expression. This will restrict + the name/value pairs that are matched to only those where the value + is exactly equal to the `value-pattern`. + --type <type>:: 'git config' will ensure that any input or output is valid under the given type constraint(s), and will canonicalize outgoing values in `<type>`'s diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index bf1bb40f63..3e49bf2210 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -28,6 +28,7 @@ SYNOPSIS [--no-notes | --notes[=<ref>]] [--interdiff=<previous>] [--range-diff=<previous> [--creation-factor=<percent>]] + [--filename-max-length=<n>] [--progress] [<common diff options>] [ <since> | <revision range> ] @@ -200,6 +201,13 @@ populated with placeholder text. allows for useful naming of a patch series, and can be combined with the `--numbered` option. +--filename-max-length=<n>:: + Instead of the standard 64 bytes, chomp the generated output + filenames at around '<n>' bytes (too short a value will be + silently raised to a reasonable length). Defaults to the + value of the `format.filenameMaxLength` configuration + variable, or 64 if unconfigured. + --rfc:: Alias for `--subject-prefix="RFC PATCH"`. RFC means "Request For Comments"; use this when sending an experimental patch for diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 59ecda6c17..b611d80697 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -20,8 +20,9 @@ DESCRIPTION This command creates an empty Git repository - basically a `.git` directory with subdirectories for `objects`, `refs/heads`, -`refs/tags`, and template files. An initial `HEAD` file that -references the HEAD of the master branch is also created. +`refs/tags`, and template files. An initial branch without any +commits will be created (see the `--initial-branch` option below +for its name). If the `$GIT_DIR` environment variable is set then it specifies a path to use instead of `./.git` for the base of the repository. @@ -73,8 +74,10 @@ If this is reinitialization, the repository will be moved to the specified path. -b <branch-name>:: --initial-branch=<branch-name>:: -Use the specified name for the initial branch in the newly created repository. -If not specified, fall back to the default name: `master`. +Use the specified name for the initial branch in the newly created +repository. If not specified, fall back to the default name (currently +`master`, but this is subject to change in the future; the name can be +customized via the `init.defaultBranch` configuration variable). --shared[=(false|true|umask|group|all|world|everybody|0xxx)]:: diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt index 6fec1eb8dc..6fe1e5e105 100644 --- a/Documentation/git-maintenance.txt +++ b/Documentation/git-maintenance.txt @@ -38,7 +38,7 @@ register:: for running in the background without disrupting foreground processes. + -The `register` subcomand will also set the `maintenance.strategy` config +The `register` subcommand will also set the `maintenance.strategy` config value to `incremental`, if this value is not previously set. The `incremental` strategy uses the following schedule for each maintenance task: @@ -101,7 +101,7 @@ This is done to avoid disrupting the remote-tracking branches. The end users expect these refs to stay unmoved unless they initiate a fetch. With prefetch task, however, the objects necessary to complete a later real fetch would already be obtained, so the real fetch would go faster. In the ideal case, -it will just become an update to bunch of remote-tracking branches without +it will just become an update to a bunch of remote-tracking branches without any object transfer. gc:: diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index ec233ac0c1..f89e68b424 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -397,7 +397,7 @@ changelist text. Exiting with a non-zero status from the script will abort the process. The purpose of the hook is to edit the message file in place, -and it is not supressed by the `--no-verify` option. This hook +and it is not suppressed by the `--no-verify` option. This hook is called even if `--prepare-p4-only` is set. p4-changelist diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt deleted file mode 100644 index a45ea1ece8..0000000000 --- a/Documentation/git-parse-remote.txt +++ /dev/null @@ -1,23 +0,0 @@ -git-parse-remote(1) -=================== - -NAME ----- -git-parse-remote - Routines to help parsing remote repository access parameters - - -SYNOPSIS --------- -[verse] -'. "$(git --exec-path)/git-parse-remote"' - -DESCRIPTION ------------ -This script is included in various scripts to supply -routines to parse files under $GIT_DIR/remotes/ and -$GIT_DIR/branches/ and configuration variables that are related -to fetching, pulling and pushing. - -GIT ---- -Part of the linkgit:git[1] suite diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 19b12b6d43..6b8ca085aa 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -109,6 +109,10 @@ 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` names an existing object of any type, `git rev-parse "$VAR^{object}"` can be used. ++ +Note that if you are verifying a name from an untrusted source, it is +wise to use `--end-of-options` so that the name argument is not mistaken +for another option. -q:: --quiet:: @@ -208,6 +212,18 @@ Options for Files Only the names of the variables are listed, not their value, even if they are set. +--path-format=(absolute|relative):: + Controls the behavior of certain other options. If specified as absolute, the + paths printed by those options will be absolute and canonical. If specified as + relative, the paths will be relative to the current working directory if that + is possible. The default is option specific. ++ +This option may be specified multiple times and affects only the arguments that +follow it on the command line, either to the end of the command line or the next +instance of this option. + +The following options are modified by `--path-format`: + --git-dir:: Show `$GIT_DIR` if defined. Otherwise show the path to the .git directory. The path shown, when relative, is @@ -217,27 +233,9 @@ If `$GIT_DIR` is not defined and the current directory is not detected to lie in a Git repository or work tree print a message to stderr and exit with nonzero status. ---absolute-git-dir:: - Like `--git-dir`, but its output is always the canonicalized - absolute path. - --git-common-dir:: Show `$GIT_COMMON_DIR` if defined, else `$GIT_DIR`. ---is-inside-git-dir:: - When the current working directory is below the repository - directory print "true", otherwise "false". - ---is-inside-work-tree:: - When the current working directory is inside the work tree of the - repository print "true", otherwise "false". - ---is-bare-repository:: - When the repository is bare print "true", otherwise "false". - ---is-shallow-repository:: - When the repository is shallow print "true", otherwise "false". - --resolve-git-dir <path>:: Check if <path> is a valid repository or a gitfile that points at a valid repository, and print the location of the @@ -251,19 +249,9 @@ print a message to stderr and exit with nonzero status. $GIT_OBJECT_DIRECTORY is set to /foo/bar then "git rev-parse --git-path objects/abc" returns /foo/bar/abc. ---show-cdup:: - When the command is invoked from a subdirectory, show the - path of the top-level directory relative to the current - directory (typically a sequence of "../", or an empty string). - ---show-prefix:: - When the command is invoked from a subdirectory, show the - path of the current directory relative to the top-level - directory. - --show-toplevel:: - Show the absolute path of the top-level directory of the working - tree. If there is no working tree, report an error. + Show the (by default, absolute) path of the top-level directory + of the working tree. If there is no working tree, report an error. --show-superproject-working-tree:: Show the absolute path of the root of the superproject's @@ -275,6 +263,36 @@ print a message to stderr and exit with nonzero status. Show the path to the shared index file in split index mode, or empty if not in split-index mode. +The following options are unaffected by `--path-format`: + +--absolute-git-dir:: + Like `--git-dir`, but its output is always the canonicalized + absolute path. + +--is-inside-git-dir:: + When the current working directory is below the repository + directory print "true", otherwise "false". + +--is-inside-work-tree:: + When the current working directory is inside the work tree of the + repository print "true", otherwise "false". + +--is-bare-repository:: + When the repository is bare print "true", otherwise "false". + +--is-shallow-repository:: + When the repository is shallow print "true", otherwise "false". + +--show-cdup:: + When the command is invoked from a subdirectory, show the + path of the top-level directory relative to the current + directory (typically a sequence of "../", or an empty string). + +--show-prefix:: + When the command is invoked from a subdirectory, show the + path of the current directory relative to the top-level + directory. + --show-object-format[=(storage|input|output)]:: Show the object format (hash algorithm) used for the repository for storage inside the `.git` directory, input, or output. For @@ -446,7 +464,7 @@ $ git rev-parse --verify HEAD * Print the commit object name from the revision in the $REV shell variable: + ------------ -$ git rev-parse --verify $REV^{commit} +$ git rev-parse --verify --end-of-options $REV^{commit} ------------ + This will error out if $REV is empty or not a valid revision. @@ -454,7 +472,7 @@ This will error out if $REV is empty or not a valid revision. * Similar to above: + ------------ -$ git rev-parse --default master --verify $REV +$ git rev-parse --default master --verify --end-of-options $REV ------------ + but if $REV is empty, the commit object name from master will be printed. diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index d401234b03..48b6683071 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -125,7 +125,8 @@ option:: start:: Start a transaction. In contrast to a non-transactional session, a transaction will automatically abort if the session ends without an - explicit commit. + explicit commit. This command may create a new empty transaction when + the current one has been committed or aborted already. prepare:: Prepare to commit the transaction. This will create lock files for all diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index af06128cc9..02a706c4c0 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -143,6 +143,11 @@ locate it. Running `repair` within the recently-moved working tree will reestablish the connection. If multiple linked working trees are moved, running `repair` from any working tree with each tree's new `<path>` as an argument, will reestablish the connection to all the specified paths. ++ +If both the main working tree and linked working trees have been moved +manually, then running `repair` in the main working tree and specifying the +new `<path>` of each linked working tree will reestablish all connections +in both directions. unlock:: diff --git a/Documentation/git.txt b/Documentation/git.txt index c463b937a8..a6d4ad0818 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -609,8 +609,8 @@ other `GIT_SEQUENCE_EDITOR`:: This environment variable overrides the configured Git editor when editing the todo list of an interactive rebase. See also - linkit::git-rebase[1] and the `sequence.editor` option in - linkit::git-config[1]. + linkgit:git-rebase[1] and the `sequence.editor` option in + linkgit:git-config[1]. `GIT_SSH`:: `GIT_SSH_COMMAND`:: diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index ffccfc7760..1f3b57d04d 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -644,7 +644,7 @@ changelist text. Exiting with a non-zero status from the script will abort the process. The purpose of the hook is to edit the message file in place, -and it is not supressed by the `--no-verify` option. This hook +and it is not suppressed by the `--no-verify` option. This hook is called even if `--prepare-p4-only` is set. Run `git-p4 submit --help` for details. diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 539b4e1997..8e333dde1b 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -7,7 +7,7 @@ gitmodules - Defining submodule properties SYNOPSIS -------- -$GIT_WORK_DIR/.gitmodules +$GIT_WORK_TREE/.gitmodules DESCRIPTION @@ -27,19 +27,19 @@ submodule.<name>.path:: Defines the path, relative to the top-level directory of the Git working tree, where the submodule is expected to be checked out. The path name must not end with a `/`. All submodule paths must - be unique within the .gitmodules file. + be unique within the `.gitmodules` file. submodule.<name>.url:: Defines a URL from which the submodule repository can be cloned. This may be either an absolute URL ready to be passed to - linkgit:git-clone[1] or (if it begins with ./ or ../) a location + linkgit:git-clone[1] or (if it begins with `./` or `../`) a location relative to the superproject's origin repository. In addition, there are a number of optional keys: submodule.<name>.update:: Defines the default update procedure for the named submodule, - i.e. how the submodule is updated by "git submodule update" + i.e. how the submodule is updated by the `git submodule update` command in the superproject. This is only used by `git submodule init` to initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase', @@ -49,7 +49,7 @@ submodule.<name>.update:: submodule.<name>.branch:: A remote branch name for tracking updates in the upstream submodule. - If the option is not specified, it defaults to the remote 'HEAD'. + If the option is not specified, it defaults to the remote `HEAD`. A special value of `.` is used to indicate that the name of the branch in the submodule should be the same name as the current branch in the current repository. See the `--remote` documentation in @@ -57,14 +57,14 @@ submodule.<name>.branch:: submodule.<name>.fetchRecurseSubmodules:: This option can be used to control recursive fetching of this - submodule. If this option is also present in the submodules entry in - .git/config of the superproject, the setting there will override the - one found in .gitmodules. + submodule. If this option is also present in the submodule's entry in + `.git/config` of the superproject, the setting there will override the + one found in `.gitmodules`. Both settings can be overridden on the command line by using the - "--[no-]recurse-submodules" option to "git fetch" and "git pull". + `--[no-]recurse-submodules` option to `git fetch` and `git pull`. submodule.<name>.ignore:: - Defines under what circumstances "git status" and the diff family show + Defines under what circumstances `git status` and the diff family show a submodule as modified. The following values are supported: + -- @@ -73,7 +73,7 @@ submodule.<name>.ignore:: been staged). dirty;; All changes to the submodule's work tree will be ignored, only - committed differences between the HEAD of the submodule and its + committed differences between the `HEAD` of the submodule and its recorded state in the superproject are taken into account. untracked;; Only untracked files in submodules will be ignored. @@ -84,12 +84,12 @@ submodule.<name>.ignore:: differences, and modifications to tracked and untracked files are shown. This is the default option. -If this option is also present in the submodules entry in .git/config +If this option is also present in the submodule's entry in `.git/config` of the superproject, the setting there will override the one found in -.gitmodules. +`.gitmodules`. Both settings can be overridden on the command line by using the -"--ignore-submodules" option. The 'git submodule' commands are not +`--ignore-submodules` option. The `git submodule` commands are not affected by this setting. -- @@ -102,7 +102,7 @@ submodule.<name>.shallow:: EXAMPLES -------- -Consider the following .gitmodules file: +Consider the following `.gitmodules` file: ---- [submodule "libfoo"] diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 090c888335..67c7a50b96 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -18,7 +18,7 @@ Untyped <<def_object,object>>, e.g. the contents of a file. [[def_branch]]branch:: - A "branch" is an active line of development. The most recent + A "branch" is a line of development. The most recent <<def_commit,commit>> on a branch is referred to as the tip of that branch. The tip of the branch is referenced by a branch <<def_head,head>>, which moves forward as additional development diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 84bbc7439a..6b59e28d44 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -252,7 +252,15 @@ endif::git-rev-list[] interpreted by linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by a colon - and zero or more comma-separated options: + and zero or more comma-separated options. + If any option is provided multiple times the + last occurance wins. ++ +The boolean options accept an optional value `[=<BOOL>]`. The values +`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean" +sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean +option is given with no value, it's enabled. ++ ** 'key=<K>': only show trailers with specified key. Matching is done case-insensitively and trailing colon is optional. If option is given multiple times trailer lines matching any of the keys are @@ -261,27 +269,25 @@ endif::git-rev-list[] desired it can be disabled with `only=false`. E.g., `%(trailers:key=Reviewed-by)` shows trailer lines with key `Reviewed-by`. -** 'only[=val]': select whether non-trailer lines from the trailer - block should be included. The `only` keyword may optionally be - followed by an equal sign and one of `true`, `on`, `yes` to omit or - `false`, `off`, `no` to show the non-trailer lines. If option is - given without value it is enabled. If given multiple times the last - value is used. +** 'only[=<BOOL>]': select whether non-trailer lines from the trailer + block should be included. ** 'separator=<SEP>': specify a separator inserted between trailer lines. When this option is not given each trailer line is terminated with a line feed character. The string SEP may contain the literal formatting codes described above. To use comma as separator one must use `%x2C` as it would otherwise be parsed as - next option. If separator option is given multiple times only the - last one is used. E.g., `%(trailers:key=Ticket,separator=%x2C )` + next option. E.g., `%(trailers:key=Ticket,separator=%x2C )` shows all trailer lines whose key is "Ticket" separated by a comma and a space. -** 'unfold[=val]': make it behave as if interpret-trailer's `--unfold` - option was given. In same way as to for `only` it can be followed - by an equal sign and explicit value. E.g., +** 'unfold[=<BOOL>]': make it behave as if interpret-trailer's `--unfold` + option was given. E.g., `%(trailers:only,unfold=true)` unfolds and shows all trailer lines. -** 'valueonly[=val]': skip over the key part of the trailer line and only - show the value part. Also this optionally allows explicit value. +** 'keyonly[=<BOOL>]': only show the key part of the trailer. +** 'valueonly[=<BOOL>]': only show the value part of the trailer. +** 'key_value_separator=<SEP>': specify a separator inserted between + trailer lines. When this option is not given each trailer key-value + pair is separated by ": ". Otherwise it shares the same semantics + as 'separator=<SEP>' above. NOTE: Some placeholders may depend on other options given to the revision traversal engine. For example, the `%g*` reflog options will diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index 6b6085585d..c65ffafc48 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -466,7 +466,7 @@ completed.) `"error"`:: This event is emitted when one of the `error()`, `die()`, - or `usage()` functions are called. + `warning()`, or `usage()` functions are called. + ------------ { diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index f9a3644711..69edf46c03 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -306,12 +306,18 @@ The remaining data of each directory block is grouped by type: The extension starts with - - 32-bit version number: the current supported version is 1. + - 32-bit version number: the current supported versions are 1 and 2. - - 64-bit time: the extension data reflects all changes through the given + - (Version 1) + 64-bit time: the extension data reflects all changes through the given time which is stored as the nanoseconds elapsed since midnight, January 1, 1970. + - (Version 2) + A null terminated string: an opaque token defined by the file system + monitor application. The extension data reflects all changes relative + to that token. + - 32-bit bitmap size: the size of the CE_FSMONITOR_VALID bitmap. - An ewah bitmap, the n-th bit indicates whether the n-th index entry diff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/technical/multi-pack-index.txt index 4e7631437a..e8e377a59f 100644 --- a/Documentation/technical/multi-pack-index.txt +++ b/Documentation/technical/multi-pack-index.txt @@ -60,10 +60,6 @@ Design Details Future Work ----------- -- Add a 'verify' subcommand to the 'git midx' builtin to verify the - contents of the multi-pack-index file match the offsets listed in - the corresponding pack-indexes. - - The multi-pack-index allows many packfiles, especially in a context where repacking is expensive (such as a very large repo), or unexpected maintenance time is unacceptable (such as a high-demand diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index f96b2e605f..96d2fc589f 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -55,6 +55,18 @@ Valid object types are: Type 5 is reserved for future expansion. Type 0 is invalid. +=== Size encoding + +This document uses the following "size encoding" of non-negative +integers: From each byte, the seven least significant bits are +used to form the resulting integer. As long as the most significant +bit is 1, this process continues; the byte with MSB 0 provides the +last seven bits. The seven-bit chunks are concatenated. Later +values are more significant. + +This size encoding should not be confused with the "offset encoding", +which is also used in this document. + === Deltified representation Conceptually there are only four object types: commit, tree, tag and @@ -73,7 +85,10 @@ Ref-delta can also refer to an object outside the pack (i.e. the so-called "thin pack"). When stored on disk however, the pack should be self contained to avoid cyclic dependency. -The delta data is a sequence of instructions to reconstruct an object +The delta data starts with the size of the base object and the +size of the object to be reconstructed. These sizes are +encoded using the size encoding from above. The remainder of +the delta data is a sequence of instructions to reconstruct the object from the base object. If the base object is deltified, it must be converted to canonical form first. Each instruction appends more and more data to the target object until it's complete. There are two diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index ba869a7d36..9dfade930d 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -27,8 +27,8 @@ and 'push-cert' capabilities are sent and recognized by the receive-pack (push to server) process. The 'ofs-delta' and 'side-band-64k' capabilities are sent and recognized -by both upload-pack and receive-pack protocols. The 'agent' capability -may optionally be sent in both protocols. +by both upload-pack and receive-pack protocols. The 'agent' and 'session-id' +capabilities may optionally be sent in both protocols. All other capabilities are only recognized by the upload-pack (fetch from server) process. @@ -365,3 +365,16 @@ If the upload-pack server advertises the 'filter' capability, fetch-pack may send "filter" commands to request a partial clone or partial fetch and request that the server omit various objects from the packfile. + +session-id=<session id> +----------------------- + +The server may advertise a session ID that can be used to identify this process +across multiple requests. The client may advertise its own session ID back to +the server as well. + +Session IDs should be unique to a given process. They must fit within a +packet-line, and must not contain non-printable or whitespace characters. The +current implementation uses trace2 session IDs (see +link:api-trace2.html[api-trace2] for details), but this may change and users of +the session ID should not rely on this fact. diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt index e597b74da3..85daeb5d9e 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/technical/protocol-v2.txt @@ -492,3 +492,16 @@ form `object-format=X`) to notify the client that the server is able to deal with objects using hash algorithm X. If not specified, the server is assumed to only handle SHA-1. If the client would like to use a hash algorithm other than SHA-1, it should specify its object-format string. + +session-id=<session id> +~~~~~~~~~~~~~~~~~~~~~~~ + +The server may advertise a session ID that can be used to identify this process +across multiple requests. The client may advertise its own session ID back to +the server as well. + +Session IDs should be unique to a given process. They must fit within a +packet-line, and must not contain non-printable or whitespace characters. The +current implementation uses trace2 session IDs (see +link:api-trace2.html[api-trace2] for details), but this may change and users of +the session ID should not rely on this fact. diff --git a/Documentation/technical/reftable.txt b/Documentation/technical/reftable.txt index 2951840e9c..8095ab2590 100644 --- a/Documentation/technical/reftable.txt +++ b/Documentation/technical/reftable.txt @@ -446,7 +446,7 @@ especially if readers will not use the object name to ref mapping. Object blocks use unique, abbreviated 2-32 object name keys, mapping to ref blocks containing references pointing to that object directly, or as the peeled value of an annotated tag. Like ref blocks, object blocks use -the file's standard block size. The abbrevation length is available in +the file's standard block size. The abbreviation length is available in the footer as `obj_id_len`. To save space in small files, object blocks may be omitted if the ref |