diff options
Diffstat (limited to 'Documentation')
41 files changed, 659 insertions, 165 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 003393ed16..65af8d82ce 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -188,6 +188,10 @@ For shell scripts specifically (not exhaustive): hopefully nobody starts using "local" before they are reimplemented in C ;-) + - Use octal escape sequences (e.g. "\302\242"), not hexadecimal (e.g. + "\xc2\xa2") in printf format strings, since hexadecimal escape + sequences are not portable. + For C programs: @@ -444,7 +448,7 @@ For C programs: - The first #include in C files, except in platform specific compat/ implementations and sha1dc/, must be either "git-compat-util.h" or one of the approved headers that includes it first for you. (The - approved headers currently include "cache.h", "builtin.h", + approved headers currently include "builtin.h", "t/helper/test-tool.h", "xdiff/xinclude.h", or "reftable/system.h"). You do not have to include more than one of these. @@ -687,7 +691,7 @@ Writing Documentation: Do: [-q | --quiet] Don't: [-q|--quiet] - Don't use spacing around "|" tokens when they're used to seperate the + Don't use spacing around "|" tokens when they're used to separate the alternate arguments of an option: Do: --track[=(direct|inherit)] Don't: --track[=(direct | inherit)] diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt index 6f606fb073..c68cdb11b9 100644 --- a/Documentation/MyFirstObjectWalk.txt +++ b/Documentation/MyFirstObjectWalk.txt @@ -126,7 +126,7 @@ parameters provided by the user over the CLI. `nr` represents the number of `rev_cmdline_entry` present in the array. -`alloc` is used by the `ALLOC_GROW` macro. Check `cache.h` - this variable is +`alloc` is used by the `ALLOC_GROW` macro. Check `alloc.h` - this variable is used to track the allocated size of the list. Per entry, we find: diff --git a/Documentation/RelNotes/2.42.0.txt b/Documentation/RelNotes/2.42.0.txt new file mode 100644 index 0000000000..9d8e50a5da --- /dev/null +++ b/Documentation/RelNotes/2.42.0.txt @@ -0,0 +1,189 @@ +Git v2.42 Release Notes +======================= + +UI, Workflows & Features + + * "git pack-refs" learns "--include" and "--exclude" to tweak the ref + hierarchy to be packed using pattern matching. + + * 'git worktree add' learned how to create a worktree based on an + orphaned branch with `--orphan`. + + * "git pack-objects" learned to invoke a new hook program that + enumerates extra objects to be used as anchoring points to keep + otherwise unreachable objects in cruft packs. + + * Add more "git var" for toolsmiths to learn various locations Git is + configured with either via the configuration or hardcoded defaults. + + * 'git notes append' was taught '--separator' to specify string to insert + between paragraphs. + + * The "git for-each-ref" family of commands learned placeholders + related to GPG signature verification. + + +Performance, Internal Implementation, Development Support etc. + + * "git diff-tree" has been taught to take advantage of the + sparse-index feature. + + * Clang's sanitizer implementation seems to work better than GCC's. + (merge d88d727143 jk/ci-use-clang-for-sanitizer-jobs later to maint). + + * The object traversal using reachability bitmap done by + "pack-object" has been tweaked to take advantage of the fact that + using "boundary" commits as representative of all the uninteresting + ones can save quite a lot of object enumeration. + + * discover_git_directory() no longer touches the_repository. + + * "git worktree" learned to work better with sparse index feature. + + * When the external merge driver is killed by a signal, its output + should not be trusted as a resolution with conflicts that is + proposed by the driver, but the code did. + + * The set-up code for the get_revision() API now allows feeding + options like --all and --not in the --stdin mode. + + * Move functions that are not about pure string manipulation out of + strbuf.[ch] + + * "imap-send" codepaths got cleaned up to get rid of unused + parameters. + + +Fixes since v2.41 +----------------- + + * "git tag" learned to leave the "$GIT_DIR/TAG_EDITMSG" file when the + command failed, so that the user can salvage what they typed. + (merge 08c12ec1d0 kh/keep-tag-editmsg-upon-failure later to maint). + + * The "-s" (silent, squelch) option of the "diff" family of commands + did not interact with other options that specify the output format + well. This has been cleaned up so that it will clear all the + formatting options given before. + (merge 9d484b92ed jc/diff-s-with-other-options later to maint). + + * Update documentation regarding Coccinelle patches. + (merge 3bd0097cfc gc/doc-cocci-updates later to maint). + + * Some atoms that can be used in "--format=<format>" for "git ls-tree" + were not supported by "git ls-files", even though they were relevant + in the context of the latter. + (merge 4d28c4f75f zh/ls-files-format-atoms later to maint). + + * Document more pseudo-refs and teach the command line completion + machinery to complete AUTO_MERGE. + (merge 982ff3a649 pb/complete-and-document-auto-merge-and-friends later to maint). + + * "git submodule" code trusted the data coming from the config (and + the in-tree .gitmodules file) too much without validating, leading + to NULL dereference if the user mucks with a repository (e.g. + submodule.<name>.url is removed). This has been corrected. + (merge fbc806acd1 tb/submodule-null-deref-fix later to maint). + + * The value of config.worktree is per-repository, but has been kept + in a singleton global variable per process. This has been OK as + most Git operations interacted with a single repository at a time, + but not right for operations like recursive "grep" that want to + access multiple repositories from a single process without forking. + + The global variable has been eliminated and made into a member in + the per-repository data structure. + (merge 3867f6d650 vd/worktree-config-is-per-repository later to maint). + + * "git [-c log.follow=true] log [--follow] ':(glob)f**'" used to barf. + (merge 8260bc5902 jk/log-follow-with-non-literal-pathspec later to maint). + + * Introduce a mechanism to disable replace refs globally and per + repository. + (merge 9c7d1b057f ds/disable-replace-refs later to maint). + + * "git cat-file --batch" and friends learned "-Z" that uses NUL + delimiter for both input and output. + (merge f79e18849b ps/cat-file-null-output later to maint). + + * The reimplemented "git add -i" did not honor color.ui configuration. + (merge 6f74648cea ds/add-i-color-configuration-fix later to maint). + + * Compilation fix for platforms without D_TYPE in struct dirent. + (merge 03bf92b9bf as/dtype-compilation-fix later to maint). + + * Suggest to refrain from using hex literals that are non-portable + when writing printf(1) format strings. + (merge f0b68f0546 jt/doc-use-octal-with-printf later to maint). + + * Simplify error message when run-command fails to start a command. + (merge 6d224ac286 rs/run-command-exec-error-on-noent later to maint). + + * Gracefully deal with a stale MIDX file that lists a packfile that + no longer exists. + (merge 06f3867865 tb/open-midx-bitmap-fallback later to maint). + + * Even when diff.ignoreSubmodules tells us to ignore submodule + changes, "git commit" with an index that already records changes to + submodules should include the submodule changes in the resulting + commit, but it did not. + (merge 5768478edc js/defeat-ignore-submodules-config-with-explicit-addition later to maint). + + * When "git commit --trailer=..." invokes the interpret-trailers + machinery, it knows what it feeds to interpret-trailers is a full + log message without any patch, but failed to express that by + passing the "--no-divider" option, which has been corrected. + (merge be3d654343 jk/commit-use-no-divider-with-interpret-trailers later to maint). + + * Avoid breakage of "git pack-objects --cruft" due to inconsistency + between the way the code enumerates packfiles in the repository. + (merge 73320e49ad tb/collect-pack-filenames-fix later to maint). + + * We create .pack and then .idx, we consider only packfiles that have + .idx usable (those with only .pack are not ready yet), so we should + remove .idx before removing .pack for consistency. + (merge 0dd1324a73 ds/remove-idx-before-pack later to maint). + + * Partially revert a sanity check that the rest of the config code + was not ready, to avoid triggering it in a corner case. + (merge a53f43f900 gc/config-partial-submodule-kvi-fix later to maint). + + * "git apply" punts when it is fed too large a patch input; the error + message it gives when it happens has been clarified. + (merge 42612e18d2 pw/apply-too-large later to maint). + + * During a cherry-pick or revert session that works on multiple + commits, "git status" did not give correct information, which has + been corrected. + (merge a096a889f4 jk/cherry-pick-revert-status later to maint). + + * A few places failed to differenciate the case where the index is + truly empty (nothing added) and we haven't yet read from the + on-disk index file, which have been corrected. + (merge 2ee045eea1 js/empty-index-fixes later to maint). + + * "git bugreport" tests did not test what it wanted to test, which + has been corrected. + (merge 1aa92b8500 ma/t0091-fixup later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 51f9d2e563 sa/doc-ls-remote later to maint). + (merge c6d26a9dda jk/format-patch-message-id-unleak later to maint). + (merge f7e063f326 ps/fetch-cleanups later to maint). + (merge e4cf013468 tl/quote-problematic-arg-for-clarity later to maint). + (merge 20025fdfc7 tz/test-ssh-verifytime-fix later to maint). + (merge e48a21df65 tz/test-fix-pthreads-prereq later to maint). + (merge 68b51172e3 mh/commit-reach-get-reachable-plug-leak later to maint). + (merge aeee1408ce kh/use-default-notes-doc later to maint). + (merge 3b8724bce6 jc/test-modernization later to maint). + (merge 447a3b7331 jc/test-modernization-2 later to maint). + (merge d57fa7fc73 la/doc-interpret-trailers later to maint). + (merge 548afb0d9a la/docs-typofixes later to maint). + (merge 3744ffcbcd rs/doc-ls-tree-hex-literal later to maint). + (merge 6c26da8404 mh/credential-erase-improvements later to maint). + (merge 78e56cff69 tz/lib-gpg-prereq-fix later to maint). + (merge 80d32e84b5 rj/leakfixes later to maint). + (merge 0a868031ed pb/complete-diff-options later to maint). + (merge d4f28279ad jc/doc-hash-object-types later to maint). + (merge 1876a5ae15 ks/t4205-test-describe-with-abbrev-fix later to maint). + (merge 6e6a529b57 jk/fsck-indices-in-worktrees later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index 0e93aef862..229b63a454 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -182,7 +182,7 @@ included, Git breaks the cycle by prohibiting these files from affecting the resolution of these conditions (thus, prohibiting them from declaring remote URLs). + -As for the naming of this keyword, it is for forwards compatibiliy with +As for the naming of this keyword, it is for forwards compatibility with a naming scheme that supports more variable-based include conditions, but currently Git only supports the exact keyword described above. diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index c96b5b2e5d..c548a91e67 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -138,4 +138,8 @@ advice.*:: checkout. diverging:: Advice shown when a fast-forward is not possible. + worktreeAddOrphan:: + Advice shown when a user tries to create a worktree from an + invalid reference, to instruct how to create a new orphan + branch instead. -- diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt index 17b4d39f89..bf9546fca4 100644 --- a/Documentation/config/feature.txt +++ b/Documentation/config/feature.txt @@ -14,6 +14,9 @@ feature.experimental:: + * `fetch.negotiationAlgorithm=skipping` may improve fetch negotiation times by skipping more commits at a time, reducing the number of round trips. ++ +* `pack.useBitmapBoundaryTraversal=true` may improve bitmap traversal times by +walking fewer objects. feature.manyFiles:: Enable config options that optimize for repos with many files in the diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index 7f95c866e1..ca47eb2008 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -130,6 +130,21 @@ or rebase occurring. Since these changes are not part of the current project most users will want to expire them sooner, which is why the default is more aggressive than `gc.reflogExpire`. +gc.recentObjectsHook:: + When considering whether or not to remove an object (either when + generating a cruft pack or storing unreachable objects as + loose), use the shell to execute the specified command(s). + Interpret their output as object IDs which Git will consider as + "recent", regardless of their age. By treating their mtimes as + "now", any objects (and their descendants) mentioned in the + output will be kept regardless of their true age. ++ +Output must contain exactly one hex object ID per line, and nothing +else. Objects which cannot be found in the repository are ignored. +Multiple hooks are supported, but all must exit successfully, else the +operation (either generating a cruft pack or unpacking unreachable +objects) will be halted. + gc.rerereResolved:: Records of conflicted merge you resolved earlier are kept for this many days when 'git rerere gc' is run. diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index d4c7c9d4e4..3748136d14 100644 --- a/Documentation/config/pack.txt +++ b/Documentation/config/pack.txt @@ -123,6 +123,23 @@ pack.useBitmaps:: true. You should not generally need to turn this off unless you are debugging pack bitmaps. +pack.useBitmapBoundaryTraversal:: + When true, Git will use an experimental algorithm for computing + reachability queries with bitmaps. Instead of building up + complete bitmaps for all of the negated tips and then OR-ing + them together, consider negated tips with existing bitmaps as + additive (i.e. OR-ing them into the result if they exist, + ignoring them otherwise), and build up a bitmap at the boundary + instead. ++ +When using this algorithm, Git may include too many objects as a result +of not opening up trees belonging to certain UNINTERESTING commits. This +inexactness matches the non-bitmap traversal algorithm. ++ +In many cases, this can provide a speed-up over the exact algorithm, +particularly when there is poor bitmap coverage of the negated side of +the query. + pack.useSparse:: When true, git will default to using the '--sparse' option in 'git pack-objects' when the '--revs' option is present. This diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 08ab86189a..9f33f88771 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -35,8 +35,11 @@ endif::git-diff[] -s:: --no-patch:: - Suppress diff output. Useful for commands like `git show` that - show the patch by default, or to cancel the effect of `--patch`. + Suppress all output from the diff machinery. Useful for + commands like `git show` that show the patch by default to + squelch their output, or to cancel the effect of options like + `--patch`, `--stat` earlier on the command line in an alias. + endif::git-format-patch[] ifdef::git-log[] diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 411de2e27d..0e4936d182 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -14,7 +14,7 @@ SYNOPSIS 'git cat-file' (-t | -s) [--allow-unknown-type] <object> 'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects] [--buffer] [--follow-symlinks] [--unordered] - [--textconv | --filters] [-z] + [--textconv | --filters] [-Z] 'git cat-file' (--textconv | --filters) [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>] @@ -243,10 +243,16 @@ respectively print: /etc/passwd -- +-Z:: + Only meaningful with `--batch`, `--batch-check`, or + `--batch-command`; input and output is NUL-delimited instead of + newline-delimited. + -z:: Only meaningful with `--batch`, `--batch-check`, or `--batch-command`; input is NUL-delimited instead of - newline-delimited. + newline-delimited. This option is deprecated in favor of + `-Z` as the output can otherwise be ambiguous. OUTPUT @@ -384,6 +390,11 @@ notdir SP <size> LF is printed when, during symlink resolution, a file is used as a directory name. +Alternatively, when `-Z` is passed, the line feeds in any of the above examples +are replaced with NUL terminators. This ensures that output will be parsable if +the output itself would contain a linefeed and is thus recommended for +scripting purposes. + CAVEATS ------- diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 0e6d9e85ec..a220afed4f 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -39,7 +39,7 @@ for later use. If the action is `reject`, git-credential will send the description to any configured credential helpers, which may erase any stored -credential matching the description. +credentials matching the description. If the action is `approve` or `reject`, no output should be emitted. diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 53f111bc0a..cf4a5a283e 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -118,7 +118,7 @@ for example: myuser:$5$.NqmNH1vwfzGpV8B$znZIcumu1tNLATgV2l6e1/mY8RzhUDHMOaVOeL1cxV3 ------ You can use the 'htpasswd' facility that comes with Apache to make these -files, but only with the -d option (or -B if your system suports it). +files, but only with the -d option (or -B if your system supports it). Preferably use the system specific utility that manages password hash creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index c6a79c2a0f..08ff715709 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -140,7 +140,7 @@ at the end. The number of additional commits is the number of commits which would be displayed by "git log v1.0.4..parent". -The hash suffix is "-g" + an unambigous abbreviation for the tip commit +The hash suffix is "-g" + an unambiguous abbreviation for the tip commit of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The length of the abbreviation scales as the repository grows, using the approximate number of objects in the repository and a bit of math @@ -203,7 +203,7 @@ BUGS Tree objects as well as tag objects not pointing at commits, cannot be described. When describing blobs, the lightweight tags pointing at blobs are ignored, -but the blob is still described as <committ-ish>:<path> despite the lightweight +but the blob is still described as <commit-ish>:<path> despite the lightweight tag being favorable. GIT diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 52b679256c..08087ffad5 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -102,7 +102,11 @@ If --merge-base is given, use the merge base of the two commits for the Just in case you are doing something exotic, it should be noted that all of the <commit> in the above description, except in the `--merge-base` case and in the last two forms that use `..` -notations, can be any <tree>. +notations, can be any <tree>. A tree of interest is the one pointed to +by the special ref `AUTO_MERGE`, which is written by the 'ort' merge +strategy upon hitting merge conflicts (see linkgit:git-merge[1]). +Comparing the working tree with `AUTO_MERGE` shows changes you've made +so far to resolve textual conflicts (see the examples below). For a more complete list of ways to spell <commit>, see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. @@ -152,6 +156,7 @@ Various ways to check your working tree:: $ git diff <1> $ git diff --cached <2> $ git diff HEAD <3> +$ git diff AUTO_MERGE <4> ------------ + <1> Changes in the working tree not yet staged for the next commit. @@ -159,6 +164,8 @@ $ git diff HEAD <3> would be committing if you run `git commit` without `-a` option. <3> Changes in the working tree since your last commit; what you would be committing if you run `git commit -a` +<4> Changes in the working tree you've made to resolve textual + conflicts so far. Comparing with arbitrary commits:: + diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 1e215d4e73..2e0318770b 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -221,6 +221,33 @@ symref:: `:lstrip` and `:rstrip` options in the same way as `refname` above. +signature:: + The GPG signature of a commit. + +signature:grade:: + Show "G" for a good (valid) signature, "B" for a bad + signature, "U" for a good signature with unknown validity, "X" + for a good signature that has expired, "Y" for a good + signature made by an expired key, "R" for a good signature + made by a revoked key, "E" if the signature cannot be + checked (e.g. missing key) and "N" for no signature. + +signature:signer:: + The signer of the GPG signature of a commit. + +signature:key:: + The key of the GPG signature of a commit. + +signature:fingerprint:: + The fingerprint of the GPG signature of a commit. + +signature:primarykeyfingerprint:: + The primary key fingerprint of the GPG signature of a commit. + +signature:trustlevel:: + The trust level of the GPG signature of a commit. Possible + outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`. + worktreepath:: The absolute path to the worktree in which the ref is checked out, if it is checked out in any linked worktree. Empty string diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index b1c13fb39a..373b46fc0d 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -245,7 +245,7 @@ populated with placeholder text. or "--reroll-count=4rev2" are allowed), but the downside of using such a reroll-count is that the range-diff/interdiff with the previous version does not state exactly which - version the new interation is compared against. + version the new iteration is compared against. --to=<email>:: Add a `To:` header to the email headers. This is in addition diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 472b5bb995..8577f7a7d4 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -3,7 +3,7 @@ git-hash-object(1) NAME ---- -git-hash-object - Compute object ID and optionally creates a blob from a file +git-hash-object - Compute object ID and optionally create an object from a file SYNOPSIS @@ -25,7 +25,8 @@ OPTIONS ------- -t <type>:: - Specify the type (default: "blob"). + Specify the type of object to be created (default: "blob"). Possible + values are `commit`, `tree`, `blob`, and `tag`. -w:: Actually write the object into the object database. diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index 4b97f812be..55d8961466 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -14,21 +14,38 @@ SYNOPSIS DESCRIPTION ----------- -Help parsing or adding 'trailers' lines, that look similar to RFC 822 e-mail +Add or parse 'trailer' lines that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit -message. +message. For example, in the following commit message -This command reads some patches or commit messages from either the -<file> arguments or the standard input if no <file> is specified. If -`--parse` is specified, the output consists of the parsed trailers. +------------------------------------------------ +subject + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. + +Signed-off-by: Alice <alice@example.com> +Signed-off-by: Bob <bob@example.com> +------------------------------------------------ + +the last two lines starting with "Signed-off-by" are trailers. +This command reads commit messages from either the +<file> arguments or the standard input if no <file> is specified. +If `--parse` is specified, the output consists of the parsed trailers. Otherwise, this command applies the arguments passed using the -`--trailer` option, if any, to the commit message part of each input -file. The result is emitted on the standard output. +`--trailer` option, if any, to each input file. The result is emitted on the +standard output. + +This command can also operate on the output of linkgit:git-format-patch[1], +which is more elaborate than a plain commit message. Namely, such output +includes a commit message (as above), a "---" divider line, and a patch part. +For these inputs, the divider and patch parts are not modified by +this command and are emitted as is on the output, unless +`--no-divider` is specified. Some configuration variables control the way the `--trailer` arguments -are applied to each commit message and the way any existing trailer in -the commit message is changed. They also make it possible to +are applied to each input and the way any existing trailer in +the input is changed. They also make it possible to automatically add some trailers. By default, a '<token>=<value>' or '<token>:<value>' argument given @@ -36,41 +53,46 @@ using `--trailer` will be appended after the existing trailers only if the last trailer has a different (<token>, <value>) pair (or if there is no existing trailer). The <token> and <value> parts will be trimmed to remove starting and trailing whitespace, and the resulting trimmed -<token> and <value> will appear in the message like this: +<token> and <value> will appear in the output like this: ------------------------------------------------ token: value ------------------------------------------------ This means that the trimmed <token> and <value> will be separated by -`': '` (one colon followed by one space). +`': '` (one colon followed by one space). For convenience, the <token> can be a +shortened string key (e.g., "sign") instead of the full string which should +appear before the separator on the output (e.g., "Signed-off-by"). This can be +configured using the 'trailer.<token>.key' configuration variable. By default the new trailer will appear at the end of all the existing trailers. If there is no existing trailer, the new trailer will appear -after the commit message part of the output, and, if there is no line -with only spaces at the end of the commit message part, one blank line -will be added before the new trailer. +at the end of the input. A blank line will be added before the new +trailer if there isn't one already. -Existing trailers are extracted from the input message by looking for +Existing trailers are extracted from the input by looking for a group of one or more lines that (i) is all trailers, or (ii) contains at least one Git-generated or user-configured trailer and consists of at least 25% trailers. The group must be preceded by one or more empty (or whitespace-only) lines. -The group must either be at the end of the message or be the last +The group must either be at the end of the input or be the last non-whitespace lines before a line that starts with '---' (followed by a -space or the end of the line). Such three minus signs start the patch -part of the message. See also `--no-divider` below. +space or the end of the line). When reading trailers, there can be no whitespace before or inside the -token, but any number of regular space and tab characters are allowed -between the token and the separator. There can be whitespaces before, -inside or after the value. The value may be split over multiple lines +<token>, but any number of regular space and tab characters are allowed +between the <token> and the separator. There can be whitespaces before, +inside or after the <value>. The <value> may be split over multiple lines with each subsequent line starting with at least one whitespace, like -the "folding" in RFC 822. +the "folding" in RFC 822. Example: + +------------------------------------------------ +token: This is a very long value, with spaces and + newlines in it. +------------------------------------------------ -Note that 'trailers' do not follow and are not intended to follow many -rules for RFC 822 headers. For example they do not follow -the encoding rules and probably many other rules. +Note that trailers do not follow (nor are they intended to follow) many of the +rules for RFC 822 headers. For example they do not follow the encoding rule. OPTIONS ------- @@ -79,12 +101,12 @@ OPTIONS --trim-empty:: If the <value> part of any trailer contains only whitespace, - the whole trailer will be removed from the resulting message. + the whole trailer will be removed from the output. This applies to existing trailers as well as new trailers. --trailer <token>[(=|:)<value>]:: Specify a (<token>, <value>) pair that should be applied as a - trailer to the input messages. See the description of this + trailer to the inputs. See the description of this command. --where <placement>:: @@ -98,7 +120,7 @@ OPTIONS --if-exists <action>:: --no-if-exists:: Specify what action will be performed when there is already at - least one trailer with the same <token> in the message. A setting + least one trailer with the same <token> in the input. A setting provided with '--if-exists' overrides all configuration variables and applies to all '--trailer' options until the next occurrence of '--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`, @@ -107,7 +129,7 @@ OPTIONS --if-missing <action>:: --no-if-missing:: Specify what action will be performed when there is no other - trailer with the same <token> in the message. A setting + trailer with the same <token> in the input. A setting provided with '--if-missing' overrides all configuration variables and applies to all '--trailer' options until the next occurrence of '--if-missing' or '--no-if-missing'. Possible actions are `doNothing` @@ -174,7 +196,7 @@ first trailer with the same <token>. trailer.ifexists:: This option makes it possible to choose what action will be performed when there is already at least one trailer with the - same <token> in the message. + same <token> in the input. + The valid values for this option are: `addIfDifferentNeighbor` (this is the default), `addIfDifferent`, `add`, `replace` or `doNothing`. @@ -184,10 +206,10 @@ trailer with the same (<token>, <value>) pair is above or below the line where the new trailer will be added. + With `addIfDifferent`, a new trailer will be added only if no trailer -with the same (<token>, <value>) pair is already in the message. +with the same (<token>, <value>) pair is already in the input. + With `add`, a new trailer will be added, even if some trailers with -the same (<token>, <value>) pair are already in the message. +the same (<token>, <value>) pair are already in the input. + With `replace`, an existing trailer with the same <token> will be deleted and the new trailer will be added. The deleted trailer will be @@ -195,12 +217,12 @@ the closest one (with the same <token>) to the place where the new one will be added. + With `doNothing`, nothing will be done; that is no new trailer will be -added if there is already one with the same <token> in the message. +added if there is already one with the same <token> in the input. trailer.ifmissing:: This option makes it possible to choose what action will be performed when there is not yet any trailer with the same - <token> in the message. + <token> in the input. + The valid values for this option are: `add` (this is the default) and `doNothing`. @@ -235,13 +257,13 @@ trailer.<token>.ifmissing:: that option for trailers with the specified <token>. trailer.<token>.command:: + Deprecated in favor of 'trailer.<token>.cmd'. This option behaves in the same way as 'trailer.<token>.cmd', except that it doesn't pass anything as argument to the specified command. Instead the first occurrence of substring $ARG is replaced by the - value that would be passed as argument. + <value> that would be passed as argument. + -The 'trailer.<token>.command' option has been deprecated in favor of -'trailer.<token>.cmd' due to the fact that $ARG in the user's command is +Note that $ARG in the user's command is only replaced once and that the original way of replacing $ARG is not safe. + When both 'trailer.<token>.cmd' and 'trailer.<token>.command' are given @@ -249,10 +271,10 @@ for the same <token>, 'trailer.<token>.cmd' is used and 'trailer.<token>.command' is ignored. trailer.<token>.cmd:: - This option can be used to specify a shell command that will be called: + This option can be used to specify a shell command that will be called once to automatically add a trailer with the specified <token>, and then - each time a '--trailer <token>=<value>' argument to modify the <value> of - the trailer that this option would produce. + called each time a '--trailer <token>=<value>' argument is specified to + modify the <value> of the trailer that this option would produce. + When the specified command is first called to add a trailer with the specified <token>, the behavior is as if a special @@ -272,37 +294,37 @@ EXAMPLES -------- * Configure a 'sign' trailer with a 'Signed-off-by' key, and then - add two of these trailers to a message: + add two of these trailers to a commit message file: + ------------ $ git config trailer.sign.key "Signed-off-by" $ cat msg.txt subject -message +body text $ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt subject -message +body text Signed-off-by: Alice <alice@example.com> Signed-off-by: Bob <bob@example.com> ------------ -* Use the `--in-place` option to edit a message file in place: +* Use the `--in-place` option to edit a commit message file in place: + ------------ $ cat msg.txt subject -message +body text Signed-off-by: Bob <bob@example.com> $ git interpret-trailers --trailer 'Acked-by: Alice <alice@example.com>' --in-place msg.txt $ cat msg.txt subject -message +body text Signed-off-by: Bob <bob@example.com> Acked-by: Alice <alice@example.com> @@ -325,7 +347,7 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re $ cat msg1.txt subject -message +body text $ git config trailer.sign.key "Signed-off-by: " $ git config trailer.sign.ifmissing add $ git config trailer.sign.ifexists doNothing @@ -333,19 +355,19 @@ $ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user. $ git interpret-trailers --trailer sign <msg1.txt subject -message +body text Signed-off-by: Bob <bob@example.com> $ cat msg2.txt subject -message +body text Signed-off-by: Alice <alice@example.com> $ git interpret-trailers --trailer sign <msg2.txt subject -message +body text Signed-off-by: Alice <alice@example.com> ------------ @@ -373,14 +395,14 @@ test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true $ cat msg.txt subject -message +body text $ git config trailer.help.key "Helped-by: " $ git config trailer.help.ifExists "addIfDifferentNeighbor" $ git config trailer.help.cmd "~/bin/glog-find-author" $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt subject -message +body text Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Christian Couder <christian.couder@gmail.com> @@ -397,14 +419,14 @@ test -n "$1" && git log --grep "$1" --pretty=reference -1 || true $ cat msg.txt subject -message +body text $ git config trailer.ref.key "Reference-to: " $ git config trailer.ref.ifExists "replace" $ git config trailer.ref.cmd "~/bin/glog-grep" $ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt subject -message +body text Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) ------------ @@ -416,7 +438,7 @@ Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) $ cat msg.txt subject -message +body text see: HEAD~2 $ cat ~/bin/glog-ref @@ -429,7 +451,7 @@ $ git config trailer.see.cmd "glog-ref" $ git interpret-trailers --trailer=see <msg.txt subject -message +body text See-also: fe3187489d69c4 (subject of related commit) ------------ diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 1abdd3c21c..1bc0328bb7 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -270,8 +270,14 @@ interpolated. The following "fieldname" are understood: objectmode:: The mode of the file which is recorded in the index. +objecttype:: + The object type of the file which is recorded in the index. objectname:: The name of the file which is recorded in the index. +objectsize[:padded]:: + The object size of the file which is recorded in the index + ("-" if the object is a `commit` or `tree`). + It also supports a padded format of size with "%(objectsize:padded)". stage:: The stage of the file which is recorded in the index. eolinfo:index:: diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index ff3da547dd..1c4f696ab5 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -96,27 +96,51 @@ OPTIONS separator (so `bar` matches `refs/heads/bar` but not `refs/heads/foobar`). +OUTPUT +------ + +The output is in the format: + +------------ +<oid> TAB <ref> LF +------------ + +When showing an annotated tag, unless `--refs` is given, two such +lines are shown: one with the refname for the tag itself as `<ref>`, +and another with `<ref>` followed by `^{}`. The `<oid>` on the latter +line shows the name of the object the tag points at. + EXAMPLES -------- +* List all references (including symbolics and pseudorefs), peeling + tags: ++ +---- +$ git ls-remote +27d43aaaf50ef0ae014b88bba294f93658016a2e HEAD +950264636c68591989456e3ba0a5442f93152c1a refs/heads/main +d9ab777d41f92a8c1684c91cfb02053d7dd1046b refs/heads/next +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} ---- -$ git ls-remote --tags . -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 -0918385dbd9656cab0d1d81ba7453d49bbc16250 refs/tags/junio-gpg-pub +* List all references matching given patterns: ++ +---- $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/seen +---- -$ git remote add korg http://www.kernel.org/pub/scm/git/git.git -$ git ls-remote --tags korg v\* -d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 -f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 -c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 -7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 +* List only tags matching a given wildcard pattern: ++ +---- +$ git ls-remote --tags http://www.kernel.org/pub/scm/git/git.git v\* +485a869c64a68cc5795dd99689797c5900f4716d refs/tags/v2.39.2 +cbf04937d5b9fcf0a76c28f69e6294e9e3ecd7e6 refs/tags/v2.39.2^{} +d4ca2e3147b409459955613c152220f4db848ee1 refs/tags/v2.40.0 +73876f4861cd3d187a4682290ab75c9dccadbc56 refs/tags/v2.40.0^{} ---- SEE ALSO diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 0240adb8ee..6572095d8d 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -86,9 +86,9 @@ OPTIONS --format=<format>:: A string that interpolates `%(fieldname)` from the result being shown. It also interpolates `%%` to `%`, and - `%xx` where `xx` are hex digits interpolates to character - with hex code `xx`; for example `%00` interpolates to - `\0` (NUL), `%09` to `\t` (TAB) and `%0a` to `\n` (LF). + `%xNN` where `NN` are hex digits interpolates to character + with hex code `NN`; for example `%x00` interpolates to + `\0` (NUL), `%x09` to `\t` (TAB) and `%x0a` to `\n` (LF). When specified, `--format` cannot be combined with other format-altering options, including `--long`, `--name-only` and `--object-only`. @@ -145,7 +145,7 @@ FIELD NAMES ----------- Various values from structured fields can be used to interpolate -into the resulting output. For each outputing line, the following +into the resulting output. For each outputting line, the following names can be used: objectmode:: diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 0aeff572a5..8625c5cb0e 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -194,9 +194,13 @@ happens: versions: stage 1 stores the version from the common ancestor, stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you can inspect the stages with `git ls-files -u`). The working - tree files contain the result of the "merge" program; i.e. 3-way + tree files contain the result of the merge operation; i.e. 3-way merge results with familiar conflict markers `<<<` `===` `>>>`. -5. No other changes are made. In particular, the local +5. A special ref `AUTO_MERGE` is written, pointing to a tree + corresponding to the current content of the working tree (including + conflict markers for textual conflicts). Note that this ref is only + written when the 'ort' merge strategy is used (the default). +6. No other changes are made. In particular, the local modifications you had before you started merge will stay the same and the index entries for them stay as they were, i.e. matching `HEAD`. @@ -336,7 +340,8 @@ You can work through the conflict with a number of tools: * Look at the diffs. `git diff` will show a three-way diff, highlighting changes from both the `HEAD` and `MERGE_HEAD` - versions. + versions. `git diff AUTO_MERGE` will show what changes you've + made so far to resolve textual conflicts. * Look at the diffs from each branch. `git log --merge -p <path>` will show diffs first for the `HEAD` version and then the diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index 466a697519..b2a2e80d42 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -33,7 +33,7 @@ from warnings to errors (so e.g. a missing "tagger" line is an error). Extra headers in the object are also an error under mktag, but ignored by linkgit:git-fsck[1]. This extra check can be turned off by setting -the appropriate `fsck.<msg-id>` varible: +the appropriate `fsck.<msg-id>` variable: git -c fsck.extraHeaderEntry=ignore mktag <my-tag-with-headers diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index efbc10f0f5..bc1bfa3791 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -9,10 +9,10 @@ SYNOPSIS -------- [verse] 'git notes' [list [<object>]] -'git notes' add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] 'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] ) -'git notes' append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] -'git notes' edit [--allow-empty] [<object>] +'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace] 'git notes' show [<object>] 'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref> 'git notes' merge --commit [-v | -q] @@ -65,7 +65,9 @@ add:: However, if you're using `add` interactively (using an editor to supply the notes contents), then - instead of aborting - the existing notes will be opened in the editor (like the `edit` - subcommand). + subcommand). If you specify multiple `-m` and `-F`, a blank + line will be inserted between the messages. Use the `--separator` + option to insert other delimiters. copy:: Copy the notes for the first object onto the second object (defaults to @@ -85,8 +87,12 @@ corresponding <to-object>. (The optional `<rest>` is ignored so that the command can read the input given to the `post-rewrite` hook.) append:: - Append to the notes of an existing object (defaults to HEAD). - Creates a new notes object if needed. + Append new message(s) given by `-m` or `-F` options to an + existing note, or add them as a new note if one does not + exist, for the object (defaults to HEAD). When appending to + an existing note, a blank line is added before each new + message as an inter-paragraph separator. The separator can + be customized with the `--separator` option. edit:: Edit the notes for a given object (defaults to HEAD). @@ -135,20 +141,26 @@ OPTIONS If multiple `-m` options are given, their values are concatenated as separate paragraphs. Lines starting with `#` and empty lines other than a - single line between paragraphs will be stripped out. + single line between paragraphs will be stripped out, + if you wish to keep them verbatim, use `--no-stripspace`. -F <file>:: --file=<file>:: Take the note message from the given file. Use '-' to read the note message from the standard input. Lines starting with `#` and empty lines other than a - single line between paragraphs will be stripped out. + single line between paragraphs will be stripped out, + if you wish to keep them verbatim, use with + `--no-stripspace` option. -C <object>:: --reuse-message=<object>:: Take the given blob object (for example, another note) as the note message. (Use `git notes copy <object>` instead to - copy notes between objects.) + copy notes between objects.). By default, message will be + copied verbatim, but if you wish to strip out the lines + starting with `#` and empty lines other than a single line + between paragraphs, use with`--stripspace` option. -c <object>:: --reedit-message=<object>:: @@ -159,6 +171,19 @@ OPTIONS Allow an empty note object to be stored. The default behavior is to automatically remove empty notes. +--[no-]separator, --separator=<paragraph-break>:: + Specify a string used as a custom inter-paragraph separator + (a newline is added at the end as needed). If `--no-separator`, no + separators will be added between paragraphs. Defaults to a blank + line. + +--[no-]stripspace:: + Strip leading and trailing whitespace from the note message. + Also strip out empty lines other than a single line between + paragraphs. For lines starting with `#` will be stripped out + in non-editor cases like "-m", "-F" and "-C", but not in + editor case like "git notes edit", "-c", etc. + --ref <ref>:: Manipulate the notes tree in <ref>. This overrides `GIT_NOTES_REF` and the "core.notesRef" configuration. The ref diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 154081f2de..284956acb3 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -8,7 +8,7 @@ git-pack-refs - Pack heads and tags for efficient repository access SYNOPSIS -------- [verse] -'git pack-refs' [--all] [--no-prune] +'git pack-refs' [--all] [--no-prune] [--include <pattern>] [--exclude <pattern>] DESCRIPTION ----------- @@ -51,14 +51,37 @@ The command by default packs all tags and refs that are already packed, and leaves other refs alone. This is because branches are expected to be actively developed and packing their tips does not help performance. -This option causes branch tips to be packed as well. Useful for -a repository with many branches of historical interests. +This option causes all refs to be packed as well, with the exception +of hidden refs, broken refs, and symbolic refs. Useful for a repository +with many branches of historical interests. --no-prune:: The command usually removes loose refs under `$GIT_DIR/refs` hierarchy after packing them. This option tells it not to. +--include <pattern>:: + +Pack refs based on a `glob(7)` pattern. Repetitions of this option +accumulate inclusion patterns. If a ref is both included in `--include` and +`--exclude`, `--exclude` takes precedence. Using `--include` will preclude all +tags from being included by default. Symbolic refs and broken refs will never +be packed. When used with `--all`, it will be a noop. Use `--no-include` to clear +and reset the list of patterns. + +--exclude <pattern>:: + +Do not pack refs matching the given `glob(7)` pattern. Repetitions of this option +accumulate exclusion patterns. Use `--no-exclude` to clear and reset the list of +patterns. If a ref is already packed, including it with `--exclude` will not +unpack it. + +When used with `--all`, pack only loose refs which do not match any of +the provided `--exclude` patterns. + +When used with `--include`, refs provided to `--include`, minus refs that are +provided to `--exclude` will be packed. + BUGS ---- diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 71f608b1ff..58cf6210cd 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -74,8 +74,7 @@ OPTIONS that is the common ancestor of all the branches. This flag tells the command to go <n> more common commits beyond that. When <n> is negative, display only the - <reference>s given, without showing the commit ancestry - tree. + <ref>s given, without showing the commit ancestry tree. --list:: Synonym to `--more=-1` @@ -88,8 +87,8 @@ OPTIONS the case of three or more commits. --independent:: - Among the <reference>s given, display only the ones that - cannot be reached from any other <reference>. + Among the <ref>s given, display only the ones that cannot be + reached from any other <ref>. --no-name:: Do not show naming strings for each commit. @@ -132,10 +131,11 @@ are mutually exclusive. OUTPUT ------ -Given N <references>, the first N lines are the one-line -description from their commit message. The branch head that is -pointed at by $GIT_DIR/HEAD is prefixed with an asterisk `*` -character while other heads are prefixed with a `!` character. + +Given N <ref>s, the first N lines are the one-line description from +their commit message. The branch head that is pointed at by +$GIT_DIR/HEAD is prefixed with an asterisk `*` character while other +heads are prefixed with a `!` character. Following these N lines, one-line log for each commit is displayed, indented N places. If a commit is on the I-th diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index d1d56f68b4..44c7387d78 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -23,7 +23,7 @@ particular ref exists. By default, shows the tags, heads, and remote refs. -The --exclude-existing form is a filter that does the inverse. It reads +The `--exclude-existing` form is a filter that does the inverse. It reads refs from stdin, one ref per line, and shows those that don't exist in the local repository. @@ -47,14 +47,14 @@ OPTIONS -d:: --dereference:: - Dereference tags into object IDs as well. They will be shown with "{caret}{}" + Dereference tags into object IDs as well. They will be shown with `{caret}{}` appended. -s:: --hash[=<n>]:: - Only show the SHA-1 hash, not the reference name. When combined with - --dereference the dereferenced tag will still be shown after the SHA-1. + Only show the OID, not the reference name. When combined with + `--dereference`, the dereferenced tag will still be shown after the OID. --verify:: @@ -70,15 +70,15 @@ OPTIONS -q:: --quiet:: - Do not print any results to stdout. When combined with `--verify` this + Do not print any results to stdout. When combined with `--verify`, this can be used to silently check if a reference exists. --exclude-existing[=<pattern>]:: - Make 'git show-ref' act as a filter that reads refs from stdin of the - form "`^(?:<anything>\s)?<refname>(?:\^{})?$`" + Make `git show-ref` act as a filter that reads refs from stdin of the + form `^(?:<anything>\s)?<refname>(?:\^{})?$` and performs the following actions on each: - (1) strip "{caret}{}" at the end of line if any; + (1) strip `{caret}{}` at the end of line if any; (2) ignore if pattern is provided and does not head-match refname; (3) warn if refname is not a well-formed refname and skip; (4) ignore if refname is a ref that exists in the local repository; @@ -96,7 +96,13 @@ OPTIONS OUTPUT ------ -The output is in the format: '<SHA-1 ID>' '<space>' '<reference name>'. +The output is in the format: + +------------ +<oid> SP <ref> LF +------------ + +For example, ----------------------------------------------------------------------------- $ git show-ref --head --dereference @@ -110,7 +116,13 @@ $ git show-ref --head --dereference ... ----------------------------------------------------------------------------- -When using --hash (and not --dereference) the output format is: '<SHA-1 ID>' +When using `--hash` (and not `--dereference`), the output is in the format: + +------------ +<oid> LF +------------ + +For example, ----------------------------------------------------------------------------- $ git show-ref --heads --hash @@ -142,10 +154,10 @@ When using the `--verify` flag, the command requires an exact path: will only match the exact branch called "master". -If nothing matches, 'git show-ref' will return an error code of 1, +If nothing matches, `git show-ref` will return an error code of 1, and in the case of verification, it will show an error message. -For scripting, you can ask it to be quiet with the "--quiet" flag, which +For scripting, you can ask it to be quiet with the `--quiet` flag, which allows you to do things like ----------------------------------------------------------------------------- @@ -157,11 +169,11 @@ to check whether a particular branch exists or not (notice how we don't actually want to show any results, and we want to use the full refname for it in order to not trigger the problem with ambiguous partial matches). -To show only tags, or only proper branch heads, use "--tags" and/or "--heads" +To show only tags, or only proper branch heads, use `--tags` and/or `--heads` respectively (using both means that it shows tags and heads, but not other random references under the refs/ subdirectory). -To do automatic tag object dereferencing, use the "-d" or "--dereference" +To do automatic tag object dereferencing, use the `-d` or `--dereference` flag, so you can do ----------------------------------------------------------------------------- diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 53dc17aa77..529a8edd9c 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -286,7 +286,7 @@ patterns in non-cone mode has a number of shortcomings: problem above? Also, if it suggests paths, what if the user has a file or directory that begins with either a '!' or '#' or has a '*', '\', '?', '[', or ']' in its name? And if it suggests paths, will - it complete "/pro" to "/proc" (in the root filesytem) rather than to + it complete "/pro" to "/proc" (in the root filesystem) rather than to "/progress.txt" in the current directory? (Note that users are likely to want to start paths with a leading '/' in non-cone mode, for the same reason that .gitignore files often have one.) diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index f4bb6114d9..06fb7f1d18 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -366,7 +366,7 @@ only the commit ends-up being in the stash and not on the current branch. # ... hack hack hack ... $ git add --patch foo # add unrelated changes to the index $ git stash push --staged # save these changes to the stash -# ... hack hack hack, finish curent changes ... +# ... hack hack hack, finish current changes ... $ git commit -m 'Massive' # commit fully tested changes $ git switch fixup-branch # switch to another branch $ git stash pop # to finish work on the saved changes diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 7f61c1edb3..d42efb3112 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -381,6 +381,16 @@ $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1 include::date-formats.txt[] +FILES +----- + +`$GIT_DIR/TAG_EDITMSG`:: + This file contains the message of an in-progress annotated + tag. If `git tag` exits due to an error before creating an + annotated tag then the tag message that has been provided by the + user in an editor session will be available in this file, but + may be overwritten by the next invocation of `git tag`. + NOTES ----- diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index f40202b8e3..c38fb3968b 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -71,6 +71,29 @@ endif::git-default-pager[] GIT_DEFAULT_BRANCH:: The name of the first branch created in newly initialized repositories. +GIT_SHELL_PATH:: + The path of the binary providing the POSIX shell for commands which use the shell. + +GIT_ATTR_SYSTEM:: + The path to the system linkgit:gitattributes[5] file, if one is enabled. + +GIT_ATTR_GLOBAL:: + The path to the global (per-user) linkgit:gitattributes[5] file. + +GIT_CONFIG_SYSTEM:: + The path to the system configuration file, if one is enabled. + +GIT_CONFIG_GLOBAL:: + The path to the global (per-user) configuration files, if any. + +Most path values contain only one value. However, some can contain multiple +values, which are separated by newlines, and are listed in order from highest to +lowest priority. Callers should be prepared for any such path value to contain +multiple items. + +Note that paths are printed even if they do not exist, but not if they are +disabled by other environment variables. + SEE ALSO -------- linkgit:git-commit-tree[1] diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 063d6eeb99..a4fbf5e838 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] - [-b <new-branch>] <path> [<commit-ish>] + [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>] 'git worktree list' [-v | --porcelain [-z]] 'git worktree lock' [--reason <string>] <worktree> 'git worktree move' <worktree> <new-path> @@ -95,6 +95,16 @@ 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 `--force` is used). ++ +If `<commit-ish>` is omitted, neither `--detach`, or `--orphan` is +used, and there are no valid local branches (or remote branches if +`--guess-remote` is specified) then, as a convenience, the new worktree is +associated with a new orphan branch named `<branch>` (after +`$(basename <path>)` if neither `-b` or `-B` is used) as if `--orphan` was +passed to the command. In the event the repository has a remote and +`--guess-remote` is used, but no remote or local branches exist, then the +command fails with a warning reminding the user to fetch from their remote +first (or override by using `-f/--force`). list:: @@ -222,6 +232,10 @@ This can also be set up as the default behaviour by using the With `prune`, do not remove anything; just report what it would remove. +--orphan:: + With `add`, make the new worktree and index empty, associating + the worktree with a new orphan/unborn branch named `<new-branch>`. + --porcelain:: With `list`, output in an easy-to-parse format for scripts. This format will remain stable across Git versions and regardless of user diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 02a3ec83e4..6deb89a296 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -1132,7 +1132,10 @@ size (see below). The merge driver is expected to leave the result of the merge in the file named with `%A` by overwriting it, and exit with zero status if it managed to merge them cleanly, or non-zero if there -were conflicts. +were conflicts. When the driver crashes (e.g. killed by SEGV), +it is expected to exit with non-zero status that are higher than +128, and in such a case, the merge results in a failure (which is +different from producing a conflict). The `merge.*.recursive` variable specifies what other merge driver to use when the merge driver is called for an internal diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 100f045bb1..65d652dc40 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -260,7 +260,7 @@ appended to its command line, which is one of: `erase`:: - Remove a matching credential, if any, from the helper's storage. + Remove matching credentials, if any, from the helper's storage. The details of the credential will be provided on the helper's stdin stream. The exact format is the same as the input/output format of the diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt index 7cee9d3689..af6bf3c45e 100644 --- a/Documentation/gitweb.txt +++ b/Documentation/gitweb.txt @@ -503,7 +503,7 @@ repositories, you can configure Apache like this: The above configuration expects your public repositories to live under `/pub/git` and will serve them as `http://git.domain.org/dir-under-pub-git`, -both as clonable Git URL and as browseable gitweb interface. If you then +both as clonable Git URL and as browsable gitweb interface. If you then start your linkgit:git-daemon[1] with `--base-path=/pub/git --export-all` then you can even use the `git://` URL with exactly the same path. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 3000888a90..e6468bf0eb 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -236,10 +236,11 @@ ifndef::git-rev-list[] endif::git-rev-list[] --stdin:: - In addition to the '<commit>' listed on the command - line, read them from the standard input. If a `--` separator is - seen, stop reading commits and start reading paths to limit the - result. + In addition to getting arguments from the command line, read + them for standard input as well. This accepts commits and + pseudo-options like `--all` and `--glob=`. When a `--` separator + is seen, the following input is treated as paths and used to + limit the result. ifdef::git-rev-list[] --quiet:: diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 9aa58052bc..6ea6c7cead 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -30,10 +30,11 @@ characters and to avoid word splitting. explicitly say 'heads/master' to tell Git which one you mean. When ambiguous, a '<refname>' is disambiguated by taking the first match in the following rules: - ++ . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually - useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD` - and `CHERRY_PICK_HEAD`); + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`, + `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD`, `BISECT_HEAD` + and `AUTO_MERGE`); . otherwise, 'refs/<refname>' if it exists; @@ -44,19 +45,38 @@ characters and to avoid word splitting. . otherwise, 'refs/remotes/<refname>' if it exists; . otherwise, 'refs/remotes/<refname>/HEAD' if it exists. + + -`HEAD` names the commit on which you based the changes in the working tree. -`FETCH_HEAD` records the branch which you fetched from a remote repository -with your last `git fetch` invocation. -`ORIG_HEAD` is created by commands that move your `HEAD` in a drastic -way (`git am`, `git merge`, `git rebase`, `git reset`), -to record the position of the `HEAD` before their operation, so that -you can easily change the tip of the branch back to the state before you ran -them. -`MERGE_HEAD` records the commit(s) which you are merging into your branch -when you run `git merge`. -`CHERRY_PICK_HEAD` records the commit which you are cherry-picking -when you run `git cherry-pick`. + `HEAD`::: + names the commit on which you based the changes in the working tree. + `FETCH_HEAD`::: + records the branch which you fetched from a remote repository with + your last `git fetch` invocation. + `ORIG_HEAD`::: + is created by commands that move your `HEAD` in a drastic way (`git + am`, `git merge`, `git rebase`, `git reset`), to record the position + of the `HEAD` before their operation, so that you can easily change + the tip of the branch back to the state before you ran them. + `MERGE_HEAD`::: + records the commit(s) which you are merging into your branch when you + run `git merge`. + `REBASE_HEAD`::: + during a rebase, records the commit at which the operation is + currently stopped, either because of conflicts or an `edit` command in + an interactive rebase. + `REVERT_HEAD`::: + records the commit which you are reverting when you run `git revert`. + `CHERRY_PICK_HEAD`::: + records the commit which you are cherry-picking when you run `git + cherry-pick`. + `BISECT_HEAD`::: + records the current commit to be tested when you run `git bisect + --no-checkout`. + `AUTO_MERGE`::: + records a tree object corresponding to the state the + 'ort' merge strategy wrote to the working tree when a merge operation + resulted in conflicts. + + Note that any of the 'refs/*' cases above may come either from the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt index 487d4d83ff..c2ba01828c 100644 --- a/Documentation/technical/api-merge.txt +++ b/Documentation/technical/api-merge.txt @@ -28,9 +28,9 @@ and `diff.c` for examples. * `struct ll_merge_options` -Check ll-merge.h for details. +Check merge-ll.h for details. Low-level (single file) merge ----------------------------- -Check ll-merge.h for details. +Check merge-ll.h for details. diff --git a/Documentation/technical/remembering-renames.txt b/Documentation/technical/remembering-renames.txt index 1e34d91390..73f41761e2 100644 --- a/Documentation/technical/remembering-renames.txt +++ b/Documentation/technical/remembering-renames.txt @@ -664,7 +664,7 @@ skip-irrelevant-renames optimization means we sometimes don't detect renames for any files within a directory that was renamed, in which case we will not have been able to detect any rename for the directory itself. In such a case, we do not know whether the directory was -renamed; we want to be careful to avoid cacheing some kind of "this +renamed; we want to be careful to avoid caching some kind of "this directory was not renamed" statement. If we did, then a subsequent commit being rebased could add a file to the old directory, and the user would expect it to end up in the correct directory -- something diff --git a/Documentation/urls-remotes.txt b/Documentation/urls-remotes.txt index e410912fe5..ae8c2db427 100644 --- a/Documentation/urls-remotes.txt +++ b/Documentation/urls-remotes.txt @@ -35,7 +35,7 @@ config file would appear like this: The `<pushurl>` is used for pushes only. It is optional and defaults to `<URL>`. Pushing to a remote affects all defined pushurls or to all defined urls if no pushurls are defined. Fetch, however, will only -fetch from the first defined url if muliple urls are defined. +fetch from the first defined url if multiple urls are defined. Named file in `$GIT_DIR/remotes` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index dc9c6a663a..4281396093 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1343,6 +1343,33 @@ $ git diff -3 file.txt # diff against stage 3 $ git diff --theirs file.txt # same as the above. ------------------------------------------------- +When using the 'ort' merge strategy (the default), before updating the working +tree with the result of the merge, Git writes a special ref named AUTO_MERGE +reflecting the state of the tree it is about to write. Conflicted paths with +textual conflicts that could not be automatically merged are written to this +tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be +used with linkgit:git-diff[1] to show the changes you've made so far to resolve +conflicts. Using the same example as above, after resolving the conflict we +get: + +------------------------------------------------- +$ git diff AUTO_MERGE +diff --git a/file.txt b/file.txt +index cd10406..8bf5ae7 100644 +--- a/file.txt ++++ b/file.txt +@@ -1,5 +1 @@ +-<<<<<<< HEAD:file.txt +-Hello world +-======= +-Goodbye +->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt ++Goodbye world +------------------------------------------------- + +Notice that the diff shows we deleted the conflict markers and both versions of +the content line, and wrote "Goodbye world" instead. + The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help for merges: @@ -4102,13 +4129,11 @@ Note that terminology has changed since that revision. For example, the README in that revision uses the word "changeset" to describe what we now call a <<def_commit_object,commit>>. -Also, we do not call it "cache" any more, but rather "index"; however, the -file is still called `cache.h`. Remark: Not much reason to change it now, -especially since there is no good single name for it anyway, because it is -basically _the_ header file which is included by _all_ of Git's C sources. +Also, we do not call it "cache" any more, but rather "index"; however, +the file is still called `read-cache.h`. If you grasp the ideas in that initial commit, you should check out a -more recent version and skim `cache.h`, `object.h` and `commit.h`. +more recent version and skim `read-cache-ll.h`, `object.h` and `commit.h`. In the early days, Git (in the tradition of UNIX) was a bunch of programs which were extremely simple, and which you used in scripts, piping the @@ -4119,11 +4144,11 @@ many of these parts have become builtins, and some of the core has been and to avoid code duplication. By now, you know what the index is (and find the corresponding data -structures in `cache.h`), and that there are just a couple of object types -(blobs, trees, commits and tags) which inherit their common structure from -`struct object`, which is their first member (and thus, you can cast e.g. -`(struct object *)commit` to achieve the _same_ as `&commit->object`, i.e. -get at the object name and flags). +structures in `read-cache-ll.h`), and that there are just a couple of +object types (blobs, trees, commits and tags) which inherit their +common structure from `struct object`, which is their first member +(and thus, you can cast e.g. `(struct object *)commit` to achieve the +_same_ as `&commit->object`, i.e. get at the object name and flags). Now is a good point to take a break to let this information sink in. |