diff options
Diffstat (limited to 'Documentation')
37 files changed, 505 insertions, 200 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index ecd0b340b1..80d1908a44 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -17,6 +17,7 @@ MAN1_TXT += git.txt MAN1_TXT += gitk.txt MAN1_TXT += gitweb.txt +# man5 / man7 guides (note: new guides should also be added to command-list.txt) MAN5_TXT += gitattributes.txt MAN5_TXT += githooks.txt MAN5_TXT += gitignore.txt @@ -294,6 +295,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-plumbingmanipulators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ + cmds-guide.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt @@ -301,7 +303,7 @@ $(cmds_txt): cmd-list.made cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) $(QUIET_GEN)$(RM) $@ && \ - $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \ + $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \ date >$@ mergetools_txt = mergetools-diff.txt mergetools-merge.txt diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index d85c9b5143..4f85a089ef 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -319,14 +319,14 @@ function body: ... git_config(git_default_config, NULL); - if (git_config_get_string_const("user.name", &cfg_name) > 0) + if (git_config_get_string_tmp("user.name", &cfg_name) > 0) printf(_("No name is found in config\n")); else printf(_("Your name: %s\n"), cfg_name); ---- `git_config()` will grab the configuration from config files known to Git and -apply standard precedence rules. `git_config_get_string_const()` will look up +apply standard precedence rules. `git_config_get_string_tmp()` will look up a specific key ("user.name") and give you the value. There are a number of single-key lookup functions like this one; you can see them all (and more info about how to use `git_config()`) in `Documentation/technical/api-config.txt`. diff --git a/Documentation/RelNotes/2.29.0.txt b/Documentation/RelNotes/2.29.0.txt index 41a2348191..334e63a497 100644 --- a/Documentation/RelNotes/2.29.0.txt +++ b/Documentation/RelNotes/2.29.0.txt @@ -15,6 +15,42 @@ UI, Workflows & Features of the title of default merge message with merge.suppressDest configuration. + * The component to respond to "git fetch" request is made more + configurable to selectively allow or reject object filtering + specification used for partial cloning. + + * Stop when "sendmail.*" configuration variables are defined, which + could be a mistaken attempt to define "sendemail.*" variables. + + * The existing backends for "git mergetool" based on variants of vim + have been refactored and then support for "nvim" has been added. + + * "git bisect" learns the "--first-parent" option to find the first + breakage along the first-parent chain. + + * "git log --first-parent -p" showed patches only for single-parent + commits on the first-parent chain; the "--first-parent" option has + been made to imply "-m". Use "--no-diff-merges" to restore the + previous behaviour to omit patches for merge commits. + + * The commit labels used to explain each side of conflicted hunks + placed by the sequencer machinery have been made more readable by + humans. + + * The "--batch-size" option of "git multi-pack-index repack" command + is now used to specify that very small packfiles are collected into + one until the total size roughly exceeds it. + + * The recent addition of SHA-256 support is marked as experimental in + the documentation. + + * "git fetch" learned --no-write-fetch-head option to avoid writing + the FETCH_HEAD file. + + * Command line completion (in contrib/) usually omits redundant, + deprecated and/or dangerous options from its output; it learned to + optionally include all of them. + Performance, Internal Implementation, Development Support etc. @@ -43,6 +79,40 @@ Performance, Internal Implementation, Development Support etc. in-core, but the check would have triggered lazy fetching of such an object from a promissor remote. + * The argv_array API is useful for not just managing argv but any + "vector" (NULL-terminated array) of strings, and has seen adoption + to a certain degree. It has been renamed to "strvec" to reduce the + barrier to adoption. + + * The final leg of SHA-256 transition plus doc updates. Note that + there is no inter-operability between SHA-1 and SHA-256 + repositories yet. + + * CMake support to build with MSVC for Windows bypassing the Makefile. + + * A new helper function has_object() has been introduced to make it + easier to mark object existence checks that do and don't want to + trigger lazy fetches, and a few such checks are converted using it. + + * A no-op replacement function implemented as a C preprocessor macro + does not perform as good a job as one implemented as a "static + inline" function in catching errors in parameters; replace the + former with the latter in <git-compat-util.h> header. + + * Test framework update. + (merge d572f52a64 es/test-cmp-typocatcher later to maint). + + * Updates to "git merge" tests, in preparation for a new merge + strategy backend. + + * midx and commit-graph files now use the byte defined in their file + format specification for identifying the hash function used for + object names. + + * The FETCH_HEAD is now always read from the filesystem regardless of + the ref backend in use, as its format is much richer than the + normal refs, and written directly by "git fetch" as a plain file.. + Fixes since v2.28 ----------------- @@ -82,6 +152,78 @@ Fixes since v2.28 * Command line completion (in contrib/) update. (merge 688b87c81b mp/complete-show-color-moved later to maint). + * All "mergy" operations that internally use the merge-recursive + machinery should honor the merge.renormalize configuration, but + many of them didn't. + + * Doc cleanup around "worktree". + (merge dc9c144be5 es/worktree-doc-cleanups later to maint). + + * The "git blame --first-parent" option was not documented, but now + it is. + (merge 11bc12ae1e rp/blame-first-parent-doc later to maint). + + * The logic to find the ref transaction hook script attempted to + cache the path to the found hook without realizing that it needed + to keep a copied value, as the API it used returned a transitory + buffer space. This has been corrected. + (merge 09b2aa30c9 ps/ref-transaction-hook later to maint). + + * Recent versions of "git diff-files" shows a diff between the index + and the working tree for "intent-to-add" paths as a "new file" + patch; "git apply --cached" should be able to take "git diff-files" + and should act as an equivalent to "git add" for the path, but the + command failed to do so for such a path. + (merge 4c025c667e rp/apply-cached-with-i-t-a later to maint). + + * "git diff [<tree-ish>] $path" for a $path that is marked with i-t-a + bit was not showing the mode bits from the working tree. + (merge cb0dd22b82 rp/ita-diff-modefix later to maint). + + * Ring buffer with size 4 used for bin-hex translation resulted in a + wrong object name in the sequencer's todo output, which has been + corrected. + (merge 5da69c0dac ak/sequencer-fix-find-uniq-abbrev later to maint). + + * When given more than one target line ranges, "git blame -La,b + -Lc,d" was over-eager to coalesce groups of original lines and + showed incorrect results, which has been corrected. + (merge c2ebaa27d6 jk/blame-coalesce-fix later to maint). + + * The regexp to identify the function boundary for FORTRAN programs + has been updated. + (merge 75c3b6b2e8 pb/userdiff-fortran-update later to maint). + + * A few end-user facing messages have been updated to be + hash-algorithm agnostic. + (merge 4279000d3e jc/object-names-are-not-sha-1 later to maint). + + * "unlink" emulation on MinGW has been optimized. + (merge 680e0b4524 jh/mingw-unlink later to maint). + + * The purpose of "git init --separate-git-dir" is to initialize a + new project with the repository separate from the working tree, + or, in the case of an existing project, to move the repository + (the .git/ directory) out of the working tree. It does not make + sense to use --separate-git-dir with a bare repository for which + there is no working tree, so disallow its use with bare + repositories. + (merge ccf236a23a es/init-no-separate-git-dir-in-bare later to maint). + + * "ls-files -o" mishandled the top-level directory of another git + working tree that hangs in the current git working tree. + (merge ab282aa548 en/dir-nonbare-embedded later to maint). + + * Fix some incorrect UNLEAK() annotations. + (merge 3e19816dc0 jk/unleak-fixes later to maint). + + * Use more buffered I/O where we used to call many small write(2)s. + (merge a698d67b08 rs/more-buffered-io later to maint). + + * The patch-id computation did not ignore the "incomplete last line" + marker like whitespaces. + (merge 82a62015a7 rs/patch-id-with-incomplete-line later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 84544f2ea3 sk/typofixes later to maint). (merge b17f411ab5 ar/help-guides-doc later to maint). @@ -89,3 +231,18 @@ Fixes since v2.28 (merge 861c4ce141 en/typofixes later to maint). (merge 60e47f6773 sg/ci-git-path-fix-with-pyenv later to maint). (merge e2bfa50ac3 jb/doc-packfile-name later to maint). + (merge 918d8ff780 es/worktree-cleanup later to maint). + (merge dc156bc31f ma/t1450-quotefix later to maint). + (merge 56e743426b en/merge-recursive-comment-fixes later to maint). + (merge 7d23ff818f rs/bisect-oid-to-hex-fix later to maint). + (merge de20baf2c9 ny/notes-doc-sample-update later to maint). + (merge f649aaaf82 so/rev-parser-errormessage-fix later to maint). + (merge 6103d58b7f bc/sha-256-cvs-svn-updates later to maint). + (merge ac900fddb7 ma/stop-progress-null-fix later to maint). + (merge e767963ab6 rs/upload-pack-sigchain-fix later to maint). + (merge a831908599 rs/preserve-merges-unused-code-removal later to maint). + (merge 6dfefe70a9 jb/commit-graph-doc-fix later to maint). + (merge 847b37271e pb/set-url-docfix later to maint). + (merge 748f733d54 mt/checkout-entry-dead-code-removal later to maint). + (merge ce820cbd58 dl/subtree-docs later to maint). + (merge 55fe225dde jk/leakfix later to maint). diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 5d122db6e9..88750af7ae 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -36,6 +36,12 @@ include::line-range-format.txt[] START. `git blame --reverse START` is taken as `git blame --reverse START..HEAD` for convenience. +--first-parent:: + Follow only the first parent commit upon seeing a merge + commit. This option can be used to determine when a line + was introduced to a particular integration branch, rather + than when it was introduced to the history overall. + -p:: --porcelain:: Show in a format designed for machine consumption. diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 5aa73cfe45..af5da45d28 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -6,9 +6,14 @@ sub format_one { my ($out, $nameattr) = @_; my ($name, $attr) = @$nameattr; my ($state, $description); + my $mansection; $state = 0; open I, '<', "$name.txt" or die "No such file $name.txt"; while (<I>) { + if (/^git[a-z0-9-]*\(([0-9])\)$/) { + $mansection = $1; + next; + } if (/^NAME$/) { $state = 1; next; @@ -27,7 +32,7 @@ sub format_one { die "No description found in $name.txt"; } if (my ($verify_name, $text) = ($description =~ /^($name) - (.*)/)) { - print $out "linkgit:$name\[1\]::\n\t"; + print $out "linkgit:$name\[$mansection\]::\n\t"; if ($attr =~ / deprecated /) { print $out "(deprecated) "; } @@ -38,12 +43,15 @@ sub format_one { } } -while (<>) { +my ($input, @categories) = @ARGV; + +open IN, "<$input"; +while (<IN>) { last if /^### command list/; } my %cmds = (); -for (sort <>) { +for (sort <IN>) { next if /^#/; chomp; @@ -51,17 +59,10 @@ for (sort <>) { $attr = '' unless defined $attr; push @{$cmds{$cat}}, [$name, " $attr "]; } +close IN; -for my $cat (qw(ancillaryinterrogators - ancillarymanipulators - mainporcelain - plumbinginterrogators - plumbingmanipulators - synchingrepositories - foreignscminterface - purehelpers - synchelpers)) { - my $out = "cmds-$cat.txt"; +for my $out (@categories) { + my ($cat) = $out =~ /^cmds-(.*)\.txt$/; open O, '>', "$out+" or die "Cannot open output file $out+"; for (@{$cmds{$cat}}) { format_one(\*O, $_); diff --git a/Documentation/config.txt b/Documentation/config.txt index ef0768b91a..3042d80978 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -348,6 +348,8 @@ include::config/diff.txt[] include::config/difftool.txt[] +include::config/extensions.txt[] + include::config/fastimport.txt[] include::config/feature.txt[] diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt new file mode 100644 index 0000000000..4e23d73cdc --- /dev/null +++ b/Documentation/config/extensions.txt @@ -0,0 +1,8 @@ +extensions.objectFormat:: + Specify the hash algorithm to use. The acceptable values are `sha1` and + `sha256`. If not specified, `sha1` is assumed. It is an error to specify + this key unless `core.repositoryFormatVersion` is 1. ++ +Note that this setting should only be set by linkgit:git-init[1] or +linkgit:git-clone[1]. Trying to change it after initialization will not +work and will produce hard-to-diagnose issues. diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt index 0006faf800..cbc5af42fd 100644 --- a/Documentation/config/sendemail.txt +++ b/Documentation/config/sendemail.txt @@ -61,3 +61,8 @@ sendemail.smtpBatchSize:: sendemail.smtpReloginDelay:: Seconds wait before reconnecting to smtp server. See also the `--relogin-delay` option of linkgit:git-send-email[1]. + +sendemail.forbidSendmailVariables:: + To avoid common misconfiguration mistakes, linkgit:git-send-email[1] + will abort with a warning if any configuration options for "sendmail" + exist. Set this variable to bypass the check. diff --git a/Documentation/config/uploadpack.txt b/Documentation/config/uploadpack.txt index ed1c835695..ee7b3ac94f 100644 --- a/Documentation/config/uploadpack.txt +++ b/Documentation/config/uploadpack.txt @@ -57,6 +57,24 @@ uploadpack.allowFilter:: If this option is set, `upload-pack` will support partial clone and partial fetch object filtering. +uploadpackfilter.allow:: + Provides a default value for unspecified object filters (see: the + below configuration variable). + Defaults to `true`. + +uploadpackfilter.<filter>.allow:: + Explicitly allow or ban the object filter corresponding to + `<filter>`, where `<filter>` may be one of: `blob:none`, + `blob:limit`, `tree`, `sparse:oid`, or `combine`. If using + combined filters, both `combine` and all of the nested filter + kinds must be allowed. Defaults to `uploadpackfilter.allow`. + +uploadpackfilter.tree.maxDepth:: + Only allow `--filter=tree=<n>` when `n` is no more than the value of + `uploadpackfilter.tree.maxDepth`. If set, this also implies + `uploadpackfilter.tree.allow=true`, unless this configuration + variable had already been set. Has no effect if unset. + uploadpack.allowRefInWant:: If this option is set, `upload-pack` will support the `ref-in-want` feature of the protocol version 2 `fetch` command. This feature diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 7987d72b02..b7af973d9c 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -73,6 +73,11 @@ ifndef::git-format-patch[] Synonym for `-p --raw`. endif::git-format-patch[] +ifdef::git-log[] +-t:: + Show the tree objects in the diff output. +endif::git-log[] + --indent-heuristic:: Enable the heuristic that shifts diff hunk boundaries to make patches easier to read. This is the default. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 6e2a160a47..e8104c082e 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -64,6 +64,15 @@ documented in linkgit:git-config[1]. --dry-run:: Show what would be done, without making any changes. +ifndef::git-pull[] +--[no-]write-fetch-head:: + Write the list of remote refs fetched in the `FETCH_HEAD` + file directly under `$GIT_DIR`. This is the default. + Passing `--no-write-fetch-head` from the command line tells + Git not to write the file. Under `--dry-run` option, the + file is never written. +endif::git-pull[] + -f:: --force:: When 'git fetch' is used with `<src>:<dst>` refspec it may @@ -186,7 +195,7 @@ ifndef::git-pull[] endif::git-pull[] --set-upstream:: - If the remote is fetched successfully, pull and add upstream + If the remote is fetched successfully, add upstream (tracking) reference, used by argument-less linkgit:git-pull[1] and other commands. For more information, see `branch.<name>.merge` and `branch.<name>.remote` in diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 7586c5a843..0e993e4587 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -17,7 +17,7 @@ The command takes various subcommands, and different options depending on the subcommand: git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>] - [--no-checkout] [<bad> [<good>...]] [--] [<paths>...] + [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...] git bisect (bad|new|<term-new>) [<rev>] git bisect (good|old|<term-old>) [<rev>...] git bisect terms [--term-good | --term-bad] @@ -365,6 +365,17 @@ does not require a checked out tree. + If the repository is bare, `--no-checkout` is assumed. +--first-parent:: ++ +Follow only the first parent commit upon seeing a merge commit. ++ +In detecting regressions introduced through the merging of a branch, the merge +commit will be identified as introduction of the bug and its ancestors will be +ignored. ++ +This option is particularly useful in avoiding false positives when a merged +branch contained broken or non-buildable commits, but the merge itself was OK. + EXAMPLES -------- diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index d34b0964be..53804cad4b 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -9,7 +9,8 @@ git-bundle - Move objects and refs by archive SYNOPSIS -------- [verse] -'git bundle' create [-q | --quiet | --progress | --all-progress] [--all-progress-implied] <file> <git-rev-list-args> +'git bundle' create [-q | --quiet | --progress | --all-progress] [--all-progress-implied] + [--version=<version>] <file> <git-rev-list-args> 'git bundle' verify [-q | --quiet] <file> 'git bundle' list-heads <file> [<refname>...] 'git bundle' unbundle <file> [<refname>...] @@ -102,6 +103,12 @@ unbundle <file>:: is activated. Unlike --all-progress this flag doesn't actually force any progress display by itself. +--version=<version>:: + Specify the bundle version. Version 2 is the older format and can only be + used with SHA-1 repositories; the newer version 3 contains capabilities that + permit extensions. The default is the oldest supported format, based on the + hash algorithm in use. + -q:: --quiet:: This flag makes the command not to report its progress diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 69c0c5c34e..44fe8860b3 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -21,8 +21,8 @@ on the standard output. If the option `--all` or `-a` is given, all available commands are printed on the standard output. -If the option `--guides` or `-g` is given, a list of the useful -Git guides is also printed on the standard output. +If the option `--guides` or `-g` is given, a list of the +Git concept guides is also printed on the standard output. If a command, or a guide, is given, a manual page for that command or guide is brought up. The 'man' program is used by default for this @@ -58,7 +58,7 @@ OPTIONS -g:: --guides:: - Prints a list of useful guides on the standard output. This + Prints a list of the Git concept guides on the standard output. This option overrides any given command or guide name. -i:: diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index ac74d058e0..af0c26232c 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -100,6 +100,8 @@ OPTIONS value is set or outside a repository. + This option cannot be used with --stdin. ++ +include::object-format-disclaimer.txt[] NOTES ----- diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index ddfe265da5..f35f70f13d 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -53,6 +53,8 @@ current working directory. Specify the given object format (hash algorithm) for the repository. The valid values are 'sha1' and (if enabled) 'sha256'. 'sha1' is the default. ++ +include::object-format-disclaimer.txt[] --template=<template_directory>:: diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 3fd26d5212..2b8ac5ff88 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -114,8 +114,51 @@ include::rev-list-options.txt[] include::pretty-formats.txt[] -COMMON DIFF OPTIONS -------------------- +DIFF FORMATTING +--------------- + +By default, `git log` does not generate any diff output. The options +below can be used to show the changes made by each commit. + +Note that unless one of `-c`, `--cc`, or `-m` is given, merge commits +will never show a diff, even if a diff format like `--patch` is +selected, nor will they match search options like `-S`. The exception is +when `--first-parent` is in use, in which merges are treated like normal +single-parent commits (this can be overridden by providing a +combined-diff option or with `--no-diff-merges`). + +-c:: + With this option, diff output for a merge commit + shows the differences from each of the parents to the merge result + simultaneously instead of showing pairwise diff between a parent + and the result one at a time. Furthermore, it lists only files + which were modified from all parents. + +--cc:: + This flag implies the `-c` option and further compresses the + patch output by omitting uninteresting hunks whose contents in + the parents have only two variants and the merge result picks + one of them without modification. + +--combined-all-paths:: + This flag causes combined diffs (used for merge commits) to + list the name of the file from all parents. It thus only has + effect when -c or --cc are specified, and is likely only + useful if filename changes are detected (i.e. when either + rename or copy detection have been requested). + +-m:: + This flag makes the merge commits show the full diff like + regular commits; for each merge parent, a separate log entry + and diff is generated. An exception is that only diff against + the first parent is shown when `--first-parent` option is given; + in that case, the output represents the changes the merge + brought _into_ the then-current branch. + +--diff-merges=off:: +--no-diff-merges:: + Disable output of diffs for merge commits (default). Useful to + override `-m`, `-c`, or `--cc`. :git-log: 1 include::diff-options.txt[] diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt index 0c6619493c..eb0caa0439 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -51,11 +51,12 @@ repack:: multi-pack-index, then divide by the total number of objects in the pack and multiply by the pack size. We select packs with expected size below the batch size until the set of packs have - total expected size at least the batch size. If the total size - does not reach the batch size, then do nothing. If a new pack- - file is created, rewrite the multi-pack-index to reference the - new pack-file. A later run of 'git multi-pack-index expire' will - delete the pack-files that were part of this batch. + total expected size at least the batch size, or all pack-files + are considered. If only one pack-file is selected, then do + nothing. If a new pack-file is created, rewrite the + multi-pack-index to reference the new pack-file. A later run of + 'git multi-pack-index expire' will delete the pack-files that + were part of this batch. + If `repack.packKeptObjects` is `false`, then any pack-files with an associated `.keep` file will not be selected for the batch to repack. diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index ced2e8280e..0a4200674c 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -223,7 +223,7 @@ are taken from notes refs. A notes ref is usually a branch which contains "files" whose paths are the object names for the objects they describe, with some directory separators included for performance reasons footnote:[Permitted pathnames have the form -'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory +'bf'`/`'fe'`/`'30'`/`'...'`/`'680d5a...': a sequence of directory names of two hexadecimal digits each followed by a filename with the rest of the object ID.]. diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index eaa2f2a404..54d715ead1 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -270,15 +270,18 @@ So does `git bundle` (see linkgit:git-bundle[1]) when it creates a bundle. This option specifies how missing objects are handled. + The form '--missing=error' requests that pack-objects stop with an error if -a missing object is encountered. This is the default action. +a missing object is encountered. If the repository is a partial clone, an +attempt to fetch missing objects will be made before declaring them missing. +This is the default action. + The form '--missing=allow-any' will allow object traversal to continue -if a missing object is encountered. Missing objects will silently be -omitted from the results. +if a missing object is encountered. No fetch of a missing object will occur. +Missing objects will silently be omitted from the results. + The form '--missing=allow-promisor' is like 'allow-any', but will only allow object traversal to continue for EXPECTED promisor missing objects. -Unexpected missing object will raise an error. +No fetch of a missing object will occur. An unexpected missing object will +raise an error. --exclude-promisor-objects:: Omit objects that are known to be in the promisor remote. (This diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt index 39b1d8eaa1..e49318a5a0 100644 --- a/Documentation/git-show-index.txt +++ b/Documentation/git-show-index.txt @@ -44,6 +44,8 @@ OPTIONS valid values are 'sha1' and (if enabled) 'sha256'. The default is the algorithm for the current repository (set by `extensions.objectFormat`), or 'sha1' if no value is set or outside a repository.. ++ +include::object-format-disclaimer.txt[] GIT --- diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 3e737c2360..d401234b03 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -148,12 +148,13 @@ still see a subset of the modifications. LOGGING UPDATES --------------- -If config parameter "core.logAllRefUpdates" is true and the ref is one under -"refs/heads/", "refs/remotes/", "refs/notes/", or the symbolic ref HEAD; or -the file "$GIT_DIR/logs/<ref>" exists then `git update-ref` will append -a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all -symbolic refs before creating the log name) describing the change -in ref value. Log lines are formatted as: +If config parameter "core.logAllRefUpdates" is true and the ref is one +under "refs/heads/", "refs/remotes/", "refs/notes/", or a pseudoref +like HEAD or ORIG_HEAD; or the file "$GIT_DIR/logs/<ref>" exists then +`git update-ref` will append a line to the log file +"$GIT_DIR/logs/<ref>" (dereferencing all symbolic refs before creating +the log name) describing the change in ref value. Log lines are +formatted as: oldsha1 SP newsha1 SP committer LF diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 4796c3c05e..6ee6ec7982 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -25,8 +25,9 @@ Manage multiple working trees attached to the same repository. A git repository can support multiple working trees, allowing you to check out more than one branch at a time. With `git worktree add` a new working tree is associated with the repository. This new working tree is called a -"linked working tree" as opposed to the "main working tree" prepared by "git -init" or "git clone". A repository has one main working tree (if it's not a +"linked working tree" as opposed to the "main working tree" prepared by +linkgit:git-init[1] or linkgit:git-clone[1]. +A repository has one main working tree (if it's not a bare repository) and zero or more linked working trees. When you are done with a linked working tree, remove it with `git worktree remove`. @@ -48,10 +49,10 @@ add <path> [<commit-ish>]:: Create `<path>` and checkout `<commit-ish>` into it. The new working directory is linked to the current repository, sharing everything except working -directory specific files such as HEAD, index, etc. `-` may also be -specified as `<commit-ish>`; it is synonymous with `@{-1}`. +directory specific files such as `HEAD`, `index`, etc. As a convenience, +`<commit-ish>` may be a bare "`-`", which is synonymous with `@{-1}`. + -If <commit-ish> is a branch name (call it `<branch>`) and is not found, +If `<commit-ish>` is a branch name (call it `<branch>`) and is not found, and neither `-b` nor `-B` nor `--detach` are used, but there does exist a tracking branch in exactly one remote (call it `<remote>`) with a matching name, treat as equivalent to: @@ -66,24 +67,24 @@ one for the purposes of disambiguation, even if the `<branch>` isn't unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin` to always checkout remote branches from there if `<branch>` is ambiguous but exists on the -'origin' remote. See also `checkout.defaultRemote` in +`origin` remote. See also `checkout.defaultRemote` in linkgit:git-config[1]. + If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used, -then, as a convenience, the new worktree is associated with a branch +then, as a convenience, the new working tree is associated with a branch (call it `<branch>`) named after `$(basename <path>)`. If `<branch>` -doesn't exist, a new branch based on HEAD is automatically created as +doesn't exist, a new branch based on `HEAD` is automatically created as if `-b <branch>` was given. If `<branch>` does exist, it will be -checked out in the new worktree, if it's not checked out anywhere -else, otherwise the command will refuse to create the worktree (unless +checked out in the new working tree, if it's not checked out anywhere +else, otherwise the command will refuse to create the working tree (unless `--force` is used). list:: -List details of each worktree. The main worktree is listed first, followed by -each of the linked worktrees. The output details include if the worktree is -bare, the revision currently checked out, and the branch currently checked out -(or 'detached HEAD' if none). +List details of each working tree. The main working tree is listed first, +followed by each of the linked working trees. The output details include +whether the working tree is bare, the revision currently checked out, and the +branch currently checked out (or "detached HEAD" if none). lock:: @@ -100,7 +101,7 @@ or linked working trees containing submodules cannot be moved. prune:: -Prune working tree information in $GIT_DIR/worktrees. +Prune working tree information in `$GIT_DIR/worktrees`. remove:: @@ -128,7 +129,7 @@ OPTIONS `move` refuses to move a locked working tree unless `--force` is specified twice. If the destination is already assigned to some other working tree but is missing (for instance, if `<new-path>` was deleted manually), then `--force` -allows the move to proceed; use --force twice if the destination is locked. +allows the move to proceed; use `--force` twice if the destination is locked. + `remove` refuses to remove an unclean working tree unless `--force` is used. To remove a locked working tree, specify `--force` twice. @@ -137,13 +138,13 @@ To remove a locked working tree, specify `--force` twice. -B <new-branch>:: With `add`, create a new branch named `<new-branch>` starting at `<commit-ish>`, and check out `<new-branch>` into the new working tree. - If `<commit-ish>` is omitted, it defaults to HEAD. + If `<commit-ish>` is omitted, it defaults to `HEAD`. By default, `-b` refuses to create a new branch if it already exists. `-B` overrides this safeguard, resetting `<new-branch>` to `<commit-ish>`. --detach:: - With `add`, detach HEAD in the new working tree. See "DETACHED HEAD" + With `add`, detach `HEAD` in the new working tree. See "DETACHED HEAD" in linkgit:git-checkout[1]. --[no-]checkout:: @@ -154,7 +155,7 @@ To remove a locked working tree, specify `--force` twice. --[no-]guess-remote:: With `worktree add <path>`, without `<commit-ish>`, instead - of creating a new branch from HEAD, if there exists a tracking + of creating a new branch from `HEAD`, if there exists a tracking branch in exactly one remote matching the basename of `<path>`, base the new branch on the remote-tracking branch, and mark the remote-tracking branch as "upstream" from the new branch. @@ -166,12 +167,12 @@ This can also be set up as the default behaviour by using the When creating a new branch, if `<commit-ish>` is a branch, mark it as "upstream" from the new branch. This is the default if `<commit-ish>` is a remote-tracking branch. See - "--track" in linkgit:git-branch[1] for details. + `--track` in linkgit:git-branch[1] for details. --lock:: Keep the working tree locked after creation. This is the equivalent of `git worktree lock` after `git worktree add`, - but without race condition. + but without a race condition. -n:: --dry-run:: @@ -185,14 +186,14 @@ This can also be set up as the default behaviour by using the -q:: --quiet:: - With 'add', suppress feedback messages. + With `add`, suppress feedback messages. -v:: --verbose:: With `prune`, report all removals. --expire <time>:: - With `prune`, only expire unused working trees older than <time>. + With `prune`, only expire unused working trees older than `<time>`. --reason <string>:: With `lock`, an explanation why the working tree is locked. @@ -202,48 +203,48 @@ This can also be set up as the default behaviour by using the absolute. + If the last path components in the working tree's path is unique among -working trees, it can be used to identify worktrees. For example if -you only have two working trees, at "/abc/def/ghi" and "/abc/def/ggg", -then "ghi" or "def/ghi" is enough to point to the former working tree. +working trees, it can be used to identify a working tree. For example if +you only have two working trees, at `/abc/def/ghi` and `/abc/def/ggg`, +then `ghi` or `def/ghi` is enough to point to the former working tree. REFS ---- In multiple working trees, some refs may be shared between all working -trees, some refs are local. One example is HEAD is different for all -working trees. This section is about the sharing rules and how to access +trees and some refs are local. One example is `HEAD` which is different for each +working tree. This section is about the sharing rules and how to access refs of one working tree from another. In general, all pseudo refs are per working tree and all refs starting -with "refs/" are shared. Pseudo refs are ones like HEAD which are -directly under GIT_DIR instead of inside GIT_DIR/refs. There is one -exception to this: refs inside refs/bisect and refs/worktree is not +with `refs/` are shared. Pseudo refs are ones like `HEAD` which are +directly under `$GIT_DIR` instead of inside `$GIT_DIR/refs`. There are +exceptions, however: refs inside `refs/bisect` and `refs/worktree` are not shared. Refs that are per working tree can still be accessed from another -working tree via two special paths, main-worktree and worktrees. The -former gives access to per-worktree refs of the main working tree, +working tree via two special paths, `main-worktree` and `worktrees`. The +former gives access to per-working tree refs of the main working tree, while the latter to all linked working trees. -For example, main-worktree/HEAD or main-worktree/refs/bisect/good -resolve to the same value as the main working tree's HEAD and -refs/bisect/good respectively. Similarly, worktrees/foo/HEAD or -worktrees/bar/refs/bisect/bad are the same as -GIT_COMMON_DIR/worktrees/foo/HEAD and -GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad. +For example, `main-worktree/HEAD` or `main-worktree/refs/bisect/good` +resolve to the same value as the main working tree's `HEAD` and +`refs/bisect/good` respectively. Similarly, `worktrees/foo/HEAD` or +`worktrees/bar/refs/bisect/bad` are the same as +`$GIT_COMMON_DIR/worktrees/foo/HEAD` and +`$GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad`. -To access refs, it's best not to look inside GIT_DIR directly. Instead +To access refs, it's best not to look inside `$GIT_DIR` directly. Instead use commands such as linkgit:git-rev-parse[1] or linkgit:git-update-ref[1] which will handle refs correctly. CONFIGURATION FILE ------------------ -By default, the repository "config" file is shared across all working +By default, the repository `config` file is shared across all working trees. If the config variables `core.bare` or `core.worktree` are already present in the config file, they will be applied to the main working trees only. In order to have configuration specific to working trees, you can turn -on "worktreeConfig" extension, e.g.: +on the `worktreeConfig` extension, e.g.: ------------ $ git config extensions.worktreeConfig true @@ -255,7 +256,7 @@ configuration in this file with `git config --worktree`. Older Git versions will refuse to access repositories with this extension. Note that in this file, the exception for `core.bare` and `core.worktree` -is gone. If you have them in $GIT_DIR/config before, you must move +is gone. If they exist in `$GIT_DIR/config`, you must move them to the `config.worktree` of the main working tree. You may also take this opportunity to review and move other configuration that you do not want to share to all working trees: @@ -268,7 +269,7 @@ do not want to share to all working trees: DETAILS ------- Each linked working tree has a private sub-directory in the repository's -$GIT_DIR/worktrees directory. The private sub-directory's name is usually +`$GIT_DIR/worktrees` directory. The private sub-directory's name is usually the base name of the linked working tree's path, possibly appended with a number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the command `git worktree add /path/other/test-next next` creates the linked @@ -276,51 +277,51 @@ working tree in `/path/other/test-next` and also creates a `$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1` if `test-next` is already taken). -Within a linked working tree, $GIT_DIR is set to point to this private +Within a linked working tree, `$GIT_DIR` is set to point to this private directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and -$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR +`$GIT_COMMON_DIR` is set to point back to the main working tree's `$GIT_DIR` (e.g. `/path/main/.git`). These settings are made in a `.git` file located at the top directory of the linked working tree. Path resolution via `git rev-parse --git-path` uses either -$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the +`$GIT_DIR` or `$GIT_COMMON_DIR` depending on the path. For example, in the linked working tree `git rev-parse --git-path HEAD` returns `/path/main/.git/worktrees/test-next/HEAD` (not `/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git rev-parse --git-path refs/heads/master` uses -$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`, -since refs are shared across all working trees, except refs/bisect and -refs/worktree. +`$GIT_COMMON_DIR` and returns `/path/main/.git/refs/heads/master`, +since refs are shared across all working trees, except `refs/bisect` and +`refs/worktree`. See linkgit:gitrepository-layout[5] for more information. The rule of thumb is do not make any assumption about whether a path belongs to -$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something -inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. +`$GIT_DIR` or `$GIT_COMMON_DIR` when you need to directly access something +inside `$GIT_DIR`. Use `git rev-parse --git-path` to get the final path. -If you manually move a linked working tree, you need to update the 'gitdir' file +If you manually move a linked working tree, you need to update the `gitdir` file in the entry's directory. For example, if a linked working tree is moved to `/newpath/test-next` and its `.git` file points to `/path/main/.git/worktrees/test-next`, then update `/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next` instead. -To prevent a $GIT_DIR/worktrees entry from being pruned (which +To prevent a `$GIT_DIR/worktrees` entry from being pruned (which can be useful in some situations, such as when the entry's working tree is stored on a portable device), use the `git worktree lock` command, which adds a file named -'locked' to the entry's directory. The file contains the reason in +`locked` to the entry's directory. The file contains the reason in plain text. For example, if a linked working tree's `.git` file points to `/path/main/.git/worktrees/test-next` then a file named `/path/main/.git/worktrees/test-next/locked` will prevent the `test-next` entry from being pruned. See linkgit:gitrepository-layout[5] for details. -When extensions.worktreeConfig is enabled, the config file +When `extensions.worktreeConfig` is enabled, the config file `.git/worktrees/<id>/config.worktree` is read after `.git/config` is. LIST OUTPUT FORMAT ------------------ -The worktree list command has two output formats. The default format shows the +The `worktree list` command has two output formats. The default format shows the details on a single line with columns. For example: ------------ @@ -333,10 +334,10 @@ $ git worktree list Porcelain Format ~~~~~~~~~~~~~~~~ The porcelain format has a line per attribute. Attributes are listed with a -label and value separated by a single space. Boolean attributes (like 'bare' -and 'detached') are listed as a label only, and are only present if and only -if the value is true. The first attribute of a worktree is always `worktree`, -an empty line indicates the end of the record. For example: +label and value separated by a single space. Boolean attributes (like `bare` +and `detached`) are listed as a label only, and are present only +if the value is true. The first attribute of a working tree is always +`worktree`, an empty line indicates the end of the record. For example: ------------ $ git worktree list --porcelain diff --git a/Documentation/git.txt b/Documentation/git.txt index 3e50065198..2fc92586b5 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -304,6 +304,13 @@ users typically do not use them directly. include::cmds-purehelpers.txt[] +Guides +------ + +The following documentation pages are guides about Git concepts. + +include::cmds-guide.txt[] + Configuration Mechanism ----------------------- @@ -497,7 +504,8 @@ double-quotes and respecting backslash escapes. E.g., the value If this variable is set, the default hash algorithm for new repositories will be set to this value. This value is currently ignored when cloning; the setting of the remote repository - is used instead. The default is "sha1". + is used instead. The default is "sha1". THIS VARIABLE IS + EXPERIMENTAL! See `--object-format` in linkgit:git-init[1]. Git Commits ~~~~~~~~~~~ diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 9e481aec85..758bf39ba3 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -3,7 +3,7 @@ gitcredentials(7) NAME ---- -gitcredentials - providing usernames and passwords to Git +gitcredentials - Providing usernames and passwords to Git SYNOPSIS -------- diff --git a/Documentation/object-format-disclaimer.txt b/Documentation/object-format-disclaimer.txt new file mode 100644 index 0000000000..4cb106f0d1 --- /dev/null +++ b/Documentation/object-format-disclaimer.txt @@ -0,0 +1,6 @@ +THIS OPTION IS EXPERIMENTAL! SHA-256 support is experimental and still +in an early stage. A SHA-256 repository will in general not be able to +share work with "regular" SHA-1 repositories. It should be assumed +that, e.g., Git internal file formats in relation to SHA-256 +repositories may change in backwards-incompatible ways. Only use +`--object-format=sha256` for testing purposes. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index b01b2b6773..002379056a 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -128,8 +128,7 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit). because merges into a topic branch tend to be only about adjusting to updated upstream from time to time, and this option allows you to ignore the individual commits - brought in to your history by such a merge. Cannot be - combined with --bisect. + brought in to your history by such a merge. --not:: Reverses the meaning of the '{caret}' prefix (or lack thereof) @@ -207,7 +206,7 @@ ifndef::git-rev-list[] Pretend as if the bad bisection ref `refs/bisect/bad` was listed and as if it was followed by `--not` and the good bisection refs `refs/bisect/good-*` on the command - line. Cannot be combined with --first-parent. + line. endif::git-rev-list[] --stdin:: @@ -743,7 +742,7 @@ outputs 'midpoint', the output of the two commands would be of roughly the same length. Finding the change which introduces a regression is thus reduced to a binary search: repeatedly generate and test new 'midpoint's until the commit chain is of length -one. Cannot be combined with --first-parent. +one. --bisect-vars:: This calculates the same as `--bisect`, except that refs in @@ -1117,48 +1116,3 @@ ifdef::git-rev-list[] by a tab. endif::git-rev-list[] endif::git-shortlog[] - -ifndef::git-shortlog[] -ifndef::git-rev-list[] -Diff Formatting -~~~~~~~~~~~~~~~ - -Listed below are options that control the formatting of diff output. -Some of them are specific to linkgit:git-rev-list[1], however other diff -options may be given. See linkgit:git-diff-files[1] for more options. - --c:: - With this option, diff output for a merge commit - shows the differences from each of the parents to the merge result - simultaneously instead of showing pairwise diff between a parent - and the result one at a time. Furthermore, it lists only files - which were modified from all parents. - ---cc:: - This flag implies the `-c` option and further compresses the - patch output by omitting uninteresting hunks whose contents in - the parents have only two variants and the merge result picks - one of them without modification. - ---combined-all-paths:: - This flag causes combined diffs (used for merge commits) to - list the name of the file from all parents. It thus only has - effect when -c or --cc are specified, and is likely only - useful if filename changes are detected (i.e. when either - rename or copy detection have been requested). - --m:: - This flag makes the merge commits show the full diff like - regular commits; for each merge parent, a separate log entry - and diff is generated. An exception is that only diff against - the first parent is shown when `--first-parent` option is given; - in that case, the output represents the changes the merge - brought _into_ the then-current branch. - --r:: - Show recursive diffs. - --t:: - Show the tree objects in the diff output. This implies `-r`. -endif::git-rev-list[] -endif::git-shortlog[] diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 2e2e7c10c6..5a60bbfa7f 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -232,9 +232,9 @@ There are some macros to easily define options: will be overwritten, so this should only be used for options where the last one specified on the command line wins. -`OPT_PASSTHRU_ARGV(short, long, &argv_array_var, arg_str, description, flags)`:: +`OPT_PASSTHRU_ARGV(short, long, &strvec_var, arg_str, description, flags)`:: Introduce an option where all instances of it on the command-line will - be reconstructed into an argv_array. This is useful when you need to + be reconstructed into a strvec. This is useful when you need to pass the command-line option, which can be specified multiple times, to another command. diff --git a/Documentation/technical/bundle-format.txt b/Documentation/technical/bundle-format.txt index 0e828151a5..bac558d049 100644 --- a/Documentation/technical/bundle-format.txt +++ b/Documentation/technical/bundle-format.txt @@ -7,6 +7,8 @@ The Git bundle format is a format that represents both refs and Git objects. We will use ABNF notation to define the Git bundle format. See protocol-common.txt for the details. +A v2 bundle looks like this: + ---- bundle = signature *prerequisite *reference LF pack signature = "# v2 git bundle" LF @@ -18,9 +20,28 @@ reference = obj-id SP refname LF pack = ... ; packfile ---- +A v3 bundle looks like this: + +---- +bundle = signature *capability *prerequisite *reference LF pack +signature = "# v3 git bundle" LF + +capability = "@" key ["=" value] LF +prerequisite = "-" obj-id SP comment LF +comment = *CHAR +reference = obj-id SP refname LF +key = 1*(ALPHA / DIGIT / "-") +value = *(%01-09 / %0b-FF) + +pack = ... ; packfile +---- + == Semantics -A Git bundle consists of three parts. +A Git bundle consists of several parts. + +* "Capabilities", which are only in the v3 format, indicate functionality that + the bundle requires to be read properly. * "Prerequisites" lists the objects that are NOT included in the bundle and the reader of the bundle MUST already have, in order to use the data in the @@ -46,3 +67,10 @@ put any string here. The reader of the bundle MUST ignore the comment. Note that the prerequisites does not represent a shallow-clone boundary. The semantics of the prerequisites and the shallow-clone boundaries are different, and the Git bundle v2 format cannot represent a shallow clone repository. + +== Capabilities + +Because there is no opportunity for negotiation, unknown capabilities cause 'git +bundle' to abort. The only known capability is `object-format`, which specifies +the hash algorithm in use, and can take the same values as the +`extensions.objectFormat` configuration value. diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/technical/commit-graph-format.txt index 440541045d..6ddbceba15 100644 --- a/Documentation/technical/commit-graph-format.txt +++ b/Documentation/technical/commit-graph-format.txt @@ -42,8 +42,13 @@ HEADER: 1-byte version number: Currently, the only valid version is 1. - 1-byte Hash Version (1 = SHA-1) - We infer the hash length (H) from this value. + 1-byte Hash Version + We infer the hash length (H) from this value: + 1 => SHA-1 + 2 => SHA-256 + If the hash type does not match the repository's hash algorithm, the + commit-graph file should be ignored with a warning presented to the + user. 1-byte number (C) of "chunks" diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index 808fa30b99..f14a7659aa 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -210,12 +210,12 @@ file. +---------------------+ | | +-----------------------+ +---------------------+ - | graph-{hash2} |->| | + | graph-{hash2} |->| | +-----------------------+ +---------------------+ | | | +-----------------------+ +---------------------+ | | | | - | graph-{hash1} |->| | + | graph-{hash1} |->| | | | | | +-----------------------+ +---------------------+ | tmp_graphXXX @@ -223,7 +223,7 @@ file. | | | | | | - | graph-{hash0} | + | graph-{hash0} | | | | | | | diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt index 5b2db3be1e..6fd20ebbc2 100644 --- a/Documentation/technical/hash-function-transition.txt +++ b/Documentation/technical/hash-function-transition.txt @@ -650,7 +650,6 @@ Some initial steps can be implemented independently of one another: The first user-visible change is the introduction of the objectFormat extension (without compatObjectFormat). This requires: -- implementing the loose-object-idx - teaching fsck about this mode of operation - using the hash function API (vtable) when computing object names - signing objects and verifying signatures @@ -658,6 +657,7 @@ extension (without compatObjectFormat). This requires: repository Next comes introduction of compatObjectFormat: +- implementing the loose-object-idx - translating object names between object formats - translating object content between object formats - generating and verifying signatures in the compat format diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt index 51a79e63de..96d89ea9b2 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/technical/http-protocol.txt @@ -401,8 +401,9 @@ at all in the request stream: The stream is terminated by a pkt-line flush (`0000`). A single "want" or "have" command MUST have one hex formatted -SHA-1 as its value. Multiple SHA-1s MUST be sent by sending -multiple commands. +object name as its value. Multiple object names MUST be sent by sending +multiple commands. Object names MUST be given using the object format +negotiated through the `object-format` capability (default SHA-1). The `have` list is created by popping the first 32 commits from `c_pending`. Less can be supplied if `c_pending` empties. diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt index faa25c5c52..f9a3644711 100644 --- a/Documentation/technical/index-format.txt +++ b/Documentation/technical/index-format.txt @@ -3,8 +3,11 @@ Git index format == The Git index file has the following format - All binary numbers are in network byte order. Version 2 is described - here unless stated otherwise. + All binary numbers are in network byte order. + In a repository using the traditional SHA-1, checksums and object IDs + (object names) mentioned below are all computed using SHA-1. Similarly, + in SHA-256 repositories, these values are computed using SHA-256. + Version 2 is described here unless stated otherwise. - A 12-byte header consisting of @@ -32,8 +35,7 @@ Git index format Extension data - - 160-bit SHA-1 over the content of the index file before this - checksum. + - Hash checksum over the content of the index file before this checksum. == Index entry @@ -80,7 +82,7 @@ Git index format 32-bit file size This is the on-disk size from stat(2), truncated to 32-bit. - 160-bit SHA-1 for the represented object + Object name for the represented object A 16-bit 'flags' field split into (high to low bits) @@ -160,8 +162,8 @@ Git index format - A newline (ASCII 10); and - - 160-bit object name for the object that would result from writing - this span of index as a tree. + - Object name for the object that would result from writing this span + of index as a tree. An entry can be in an invalidated state and is represented by having a negative number in the entry_count field. In this case, there is no @@ -198,7 +200,7 @@ Git index format stage 1 to 3 (a missing stage is represented by "0" in this field); and - - At most three 160-bit object names of the entry in stages from 1 to 3 + - At most three object names of the entry in stages from 1 to 3 (nothing is written for a missing stage). === Split index @@ -211,8 +213,8 @@ Git index format 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 + - Hash of the shared index file. The shared index file path + is $GIT_DIR/sharedindex.<hash>. If all bits are zero, the index does not require a shared index file. - An ewah-encoded delete bitmap, each bit represents an entry in the @@ -253,10 +255,10 @@ Git index format - 32-bit dir_flags (see struct dir_struct) - - 160-bit SHA-1 of $GIT_DIR/info/exclude. Null SHA-1 means the file + - Hash of $GIT_DIR/info/exclude. A null hash means the file does not exist. - - 160-bit SHA-1 of core.excludesfile. Null SHA-1 means the file does + - Hash of core.excludesfile. A null hash means the file does not exist. - NUL-terminated string of per-dir exclude file name. This usually @@ -285,13 +287,13 @@ The remaining data of each directory block is grouped by type: - An ewah bitmap, the n-th bit records "check-only" bit of read_directory_recursive() for the n-th directory. - - An ewah bitmap, the n-th bit indicates whether SHA-1 and stat data + - An ewah bitmap, the n-th bit indicates whether hash and stat data is valid for the n-th directory and exists in the next data. - An array of stat data. The n-th data corresponds with the n-th "one" bit in the previous ewah bitmap. - - An array of SHA-1. The n-th SHA-1 corresponds with the n-th "one" bit + - An array of hashes. The n-th hash corresponds with the n-th "one" bit in the previous ewah bitmap. - One NUL. @@ -330,12 +332,12 @@ The remaining data of each directory block is grouped by type: - 32-bit offset to the end of the index entries - - 160-bit SHA-1 over the extension types and their sizes (but not + - Hash over the extension types and their sizes (but not their contents). E.g. if we have "TREE" extension that is N-bytes long, "REUC" extension that is M-bytes long, followed by "EOIE", then the hash would be: - SHA-1("TREE" + <binary representation of N> + + Hash("TREE" + <binary representation of N> + "REUC" + <binary representation of M>) == Index Entry Offset Table diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index d3a142c652..f96b2e605f 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -1,6 +1,12 @@ Git pack format =============== +== Checksums and object IDs + +In a repository using the traditional SHA-1, pack checksums, index checksums, +and object IDs (object names) mentioned below are all computed using SHA-1. +Similarly, in SHA-256 repositories, these values are computed using SHA-256. + == pack-*.pack files have the following format: - A header appears at the beginning and consists of the following: @@ -26,7 +32,7 @@ Git pack format (deltified representation) n-byte type and length (3-bit type, (n-1)*7+4-bit length) - 20-byte base object name if OBJ_REF_DELTA or a negative relative + base object name if OBJ_REF_DELTA or a negative relative offset from the delta object's position in the pack if this is an OBJ_OFS_DELTA object compressed delta data @@ -34,7 +40,7 @@ Git pack format Observation: length of each object is encoded in a variable length format and is not constrained to 32-bit or anything. - - The trailer records 20-byte SHA-1 checksum of all of the above. + - The trailer records a pack checksum of all of the above. === Object types @@ -58,8 +64,8 @@ ofs-delta and ref-delta, which is only valid in a pack file. Both ofs-delta and ref-delta store the "delta" to be applied to another object (called 'base object') to reconstruct the object. The -difference between them is, ref-delta directly encodes 20-byte base -object name. If the base object is in the same pack, ofs-delta encodes +difference between them is, ref-delta directly encodes base object +name. If the base object is in the same pack, ofs-delta encodes the offset of the base object in the pack instead. The base object could also be deltified if it's in the same pack. @@ -143,14 +149,14 @@ This is the instruction reserved for future expansion. object is stored in the packfile as the offset from the beginning. - 20-byte object name. + one object name of the appropriate size. - The file is concluded with a trailer: - A copy of the 20-byte SHA-1 checksum at the end of - corresponding packfile. + A copy of the pack checksum at the end of the corresponding + packfile. - 20-byte SHA-1-checksum of all of the above. + Index checksum of all of the above. Pack Idx file: @@ -198,7 +204,7 @@ Pack file entry: <+ If it is not DELTA, then deflated bytes (the size above is the size before compression). If it is REF_DELTA, then - 20-byte base object name SHA-1 (the size above is the + base object name (the size above is the size of the delta data that follows). delta data, deflated. If it is OFS_DELTA, then @@ -227,9 +233,9 @@ Pack file entry: <+ - A 256-entry fan-out table just like v1. - - A table of sorted 20-byte SHA-1 object names. These are - packed together without offset values to reduce the cache - footprint of the binary search for a specific object name. + - A table of sorted object names. These are packed together + without offset values to reduce the cache footprint of the + binary search for a specific object name. - A table of 4-byte CRC32 values of the packed object data. This is new in v2 so compressed data can be copied directly @@ -248,10 +254,10 @@ Pack file entry: <+ - The same trailer as a v1 pack file: - A copy of the 20-byte SHA-1 checksum at the end of + A copy of the pack checksum at the end of corresponding packfile. - 20-byte SHA-1-checksum of all of the above. + Index checksum of all of the above. == multi-pack-index (MIDX) files have the following format: @@ -273,7 +279,12 @@ HEADER: Git only writes or recognizes version 1. 1-byte Object Id Version - Git only writes or recognizes version 1 (SHA1). + We infer the length of object IDs (OIDs) from this value: + 1 => SHA-1 + 2 => SHA-256 + If the hash type does not match the repository's hash algorithm, + the multi-pack-index file should be ignored with a warning + presented to the user. 1-byte number of "chunks" @@ -329,4 +340,4 @@ CHUNK DATA: TRAILER: - 20-byte SHA1-checksum of the above contents. + Index checksum of the above contents. diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt index 36ccd14f97..124d716807 100644 --- a/Documentation/technical/protocol-capabilities.txt +++ b/Documentation/technical/protocol-capabilities.txt @@ -324,15 +324,19 @@ allow-tip-sha1-in-want ---------------------- If the upload-pack server advertises this capability, fetch-pack may -send "want" lines with SHA-1s that exist at the server but are not -advertised by upload-pack. +send "want" lines with object names that exist at the server but are not +advertised by upload-pack. For historical reasons, the name of this +capability contains "sha1". Object names are always given using the +object format negotiated through the 'object-format' capability. allow-reachable-sha1-in-want ---------------------------- If the upload-pack server advertises this capability, fetch-pack may -send "want" lines with SHA-1s that exist at the server but are not -advertised by upload-pack. +send "want" lines with object names that exist at the server but are not +advertised by upload-pack. For historical reasons, the name of this +capability contains "sha1". Object names are always given using the +object format negotiated through the 'object-format' capability. push-cert=<nonce> ----------------- diff --git a/Documentation/technical/shallow.txt b/Documentation/technical/shallow.txt index 01dedfe9ff..f3738baa0f 100644 --- a/Documentation/technical/shallow.txt +++ b/Documentation/technical/shallow.txt @@ -13,7 +13,7 @@ pretend as if they are root commits (e.g. "git log" traversal stops after showing them; "git fsck" does not complain saying the commits listed on their "parent" lines do not exist). -Each line contains exactly one SHA-1. When read, a commit_graft +Each line contains exactly one object name. When read, a commit_graft will be constructed, which has nr_parent < 0 to make it easier to discern from user provided grafts. |