diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/CodingGuidelines | 7 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.36.0.txt | 183 | ||||
| -rw-r--r-- | Documentation/SubmittingPatches | 36 | ||||
| -rw-r--r-- | Documentation/config.txt | 35 | ||||
| -rw-r--r-- | Documentation/config/fetch.txt | 25 | ||||
| -rw-r--r-- | Documentation/config/gpg.txt | 4 | ||||
| -rw-r--r-- | Documentation/config/stash.txt | 7 | ||||
| -rw-r--r-- | Documentation/diff-options.txt | 21 | ||||
| -rw-r--r-- | Documentation/fetch-options.txt | 1 | ||||
| -rw-r--r-- | Documentation/git-cat-file.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-check-ignore.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-checkout-index.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-hook.txt | 45 | ||||
| -rw-r--r-- | Documentation/git-mktree.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-name-rev.txt | 30 | ||||
| -rw-r--r-- | Documentation/gitattributes.txt | 11 | ||||
| -rw-r--r-- | Documentation/gitcli.txt | 19 | ||||
| -rw-r--r-- | Documentation/githooks.txt | 4 | ||||
| -rw-r--r-- | Documentation/rev-list-options.txt | 22 | ||||
| -rw-r--r-- | Documentation/technical/multi-pack-index.txt | 1 | ||||
| -rw-r--r-- | Documentation/technical/pack-format.txt | 13 |
21 files changed, 431 insertions, 59 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 0e27b5395d..c37c43186e 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -26,6 +26,13 @@ code. For Git in general, a few rough rules are: go and fix it up." Cf. http://lkml.iu.edu/hypermail/linux/kernel/1001.3/01069.html + - Log messages to explain your changes are as important as the + changes themselves. Clearly written code and in-code comments + explain how the code works and what is assumed from the surrounding + context. The log messages explain what the changes wanted to + achieve and why the changes were necessary (more on this in the + accompanying SubmittingPatches document). + Make your code readable and sensible, and don't try to be clever. As for more concrete guidelines, just imitate the existing code diff --git a/Documentation/RelNotes/2.36.0.txt b/Documentation/RelNotes/2.36.0.txt new file mode 100644 index 0000000000..3e1261c584 --- /dev/null +++ b/Documentation/RelNotes/2.36.0.txt @@ -0,0 +1,183 @@ +Git 2.36 Release Notes +====================== + +Updates since Git 2.35 +---------------------- + +Backward compatibility warts + + * "git name-rev --stdin" has been deprecated and issues a warning + when used; use "git name-rev --annotate-stdin" instead. + + +Note to those who build from the source + + * + + +UI, Workflows & Features + + * Assorted updates to "git cat-file", especially "-h". + + * The command line completion (in contrib/) learns to complete + arguments to give to "git sparse-checkout" command. + + * "git log --remerge-diff" shows the difference from mechanical merge + result and the result that is actually recorded in a merge commit. + + * "git log" and friends learned an option --exclude-first-parent-only + to propagate UNINTERESTING bit down only along the first-parent + chain, just like --first-parent option shows commits that lack the + UNINTERESTING bit only along the first-parent chain. + + * The command line completion script (in contrib/) learned to + complete all Git subcommands, including the ones that are normally + hidden, when GIT_COMPLETION_SHOW_ALL_COMMANDS is used. + + +Performance, Internal Implementation, Development Support etc. + + * "git apply" (ab)used the util pointer of the string-list to keep + track of how each symbolic link needs to be handled, which has been + simplified by using strset. + + * Fix a hand-rolled alloca() imitation that may have violated + alignment requirement of data being sorted in compatibility + implementation of qsort_s() and stable qsort(). + + * Use the parse-options API in "git reflog" command. + + * The conditional inclusion mechanism of configuration files using + "[includeIf <condition>]" learns to base its decision on the + URL of the remote repository the repository interacts with. + (merge 399b198489 jt/conditional-config-on-remote-url later to maint). + + * "git name-rev --stdin" does not behave like usual "--stdin" at + all. Start the process of renaming it to "--annotate-stdin". + (merge a2585719b3 jc/name-rev-stdin later to maint). + + * "git update-index", "git checkout-index", and "git clean" are + taught to work better with the sparse checkout feature. + + +Fixes since v2.35 +----------------- + + * "rebase" and "stash" in secondary worktrees are broken in + Git 2.35.0, which has been corrected. + + * "git pull --rebase" ignored the rebase.autostash configuration + variable when the remote history is a descendant of our history, + which has been corrected. + (merge 3013d98d7a pb/pull-rebase-autostash-fix later to maint). + + * "git update-index --refresh" has been taught to deal better with + racy timestamps (just like "git status" already does). + (merge 2ede073fd2 ms/update-index-racy later to maint). + + * Avoid tests that are run under GIT_TRACE2 set from failing + unnecessarily. + (merge 944d808e42 js/test-unset-trace2-parents later to maint). + + * The merge-ort misbehaved when merge.renameLimit configuration is + set too low and failed to find all renames. + (merge 9ae39fef7f en/merge-ort-restart-optim-fix later to maint). + + * We explain that revs come first before the pathspec among command + line arguments, but did not spell out that dashed options come + before other args, which has been corrected. + (merge c11f95010c tl/doc-cli-options-first later to maint). + + * "git add -p" rewritten in C regressed hunk splitting in some cases, + which has been corrected. + (merge 7008ddc645 pw/add-p-hunk-split-fix later to maint). + + * "git fetch --negotiate-only" is an internal command used by "git + push" to figure out which part of our history is missing from the + other side. It should never recurse into submodules even when + fetch.recursesubmodules configuration variable is set, nor it + should trigger "gc". The code has been tightened up to ensure it + only does common ancestry discovery and nothing else. + (merge de4eaae63a gc/fetch-negotiate-only-early-return later to maint). + + * The code path that verifies signatures made with ssh were made to + work better on a system with CRLF line endings. + (merge caeef01ea7 fs/ssh-signing-crlf later to maint). + + * "git sparse-checkout init" failed to write into $GIT_DIR/info + directory when the repository was created without one, which has + been corrected to auto-create it. + (merge 7f44842ac1 jt/sparse-checkout-leading-dir-fix later to maint). + + * Cloning from a repository that does not yet have any branches or + tags but has other refs resulted in a "remote transport reported + error", which has been corrected. + (merge dccea605b6 jt/clone-not-quite-empty later to maint). + + * Mark in various places in the code that the sparse index and the + split index features are mutually incompatible. + (merge 451b66c533 js/sparse-vs-split-index later to maint). + + * Update the logic to compute alignment requirement for our mem-pool. + (merge e38bcc66d8 jc/mem-pool-alignment later to maint). + + * Pick a better random number generator and use it when we prepare + temporary filenames. + (merge 47efda967c bc/csprng-mktemps later to maint). + + * Update the contributor-facing documents on proposed log messages. + (merge cdba0295b0 jc/doc-log-messages later to maint). + + * When "git fetch --prune" failed to prune the refs it wanted to + prune, the command issued error messages but exited with exit + status 0, which has been corrected. + (merge c9e04d905e tg/fetch-prune-exit-code-fix later to maint). + + * Problems identified by Coverity in the reftable code have been + corrected. + (merge 01033de49f hn/reftable-coverity-fixes later to maint). + + * A bug that made multi-pack bitmap and the object order out-of-sync, + making the .midx data corrupt, has been fixed. + (merge f8b60cf99b tb/midx-bitmap-corruption-fix later to maint). + + * The build procedure has been taught to notice older version of zlib + and enable our replacement uncompress2() automatically. + (merge 07564773c2 ab/auto-detect-zlib-compress2 later to maint). + + * Interaction between fetch.negotiationAlgorithm and + feature.experimental configuration variables has been corrected. + (merge 714edc620c en/fetch-negotiation-default-fix later to maint). + + * "git diff --diff-filter=aR" is now parsed correctly. + (merge 75408ca949 js/diff-filter-negation-fix later to maint). + + * When "git subtree" wants to create a merge, it used "git merge" and + let it be affected by end-user's "merge.ff" configuration, which + has been corrected. + (merge 9158a3564a tk/subtree-merge-not-ff-only later to maint). + + * Unlike "git apply", "git patch-id" did not handle patches with + hunks that has only 1 line in either preimage or postimage, which + has been corrected. + (merge 757e75c81e jz/patch-id-hunk-header-parsing-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge cfc5cf428b jc/find-header later to maint). + (merge 40e7cfdd46 jh/p4-fix-use-of-process-error-exception later to maint). + (merge 727e6ea350 jh/p4-spawning-external-commands-cleanup later to maint). + (merge 0a6adc26e2 rs/grep-expr-cleanup later to maint). + (merge 4ed7dfa713 po/readme-mention-contributor-hints later to maint). + (merge 6046f7a91c en/plug-leaks-in-merge later to maint). + (merge 8c591dbfce bc/clarify-eol-attr later to maint). + (merge 518e15db74 rs/parse-options-lithelp-help later to maint). + (merge cbac0076ef gh/doc-typos later to maint). + (merge ce14de03db ab/no-errno-from-resolve-ref-unsafe later to maint). + (merge 2826ffad8c rc/negotiate-only-typofix later to maint). + (merge 0f03f04c5c en/sparse-checkout-leakfix later to maint). + (merge 74f3390dde sy/diff-usage-typofix later to maint). + (merge 45d0212a71 ll/doc-mktree-typofix later to maint). + (merge e9b272e4c1 js/no-more-legacy-stash later to maint). + (merge 6798b08e84 ab/do-not-hide-failures-in-git-dot-pm later to maint). + (merge 9325285df4 po/doc-check-ignore-markup-fix later to maint). + (merge cd26cd6c7c sy/modernize-t-lib-read-tree-m-3way later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 92b80d94d4..a6121d1d42 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -110,6 +110,35 @@ run `git diff --check` on your changes before you commit. [[describe-changes]] === Describe your changes well. +The log message that explains your changes is just as important as the +changes themselves. Your code may be clearly written with in-code +comment to sufficiently explain how it works with the surrounding +code, but those who need to fix or enhance your code in the future +will need to know _why_ your code does what it does, for a few +reasons: + +. Your code may be doing something differently from what you wanted it + to do. Writing down what you actually wanted to achieve will help + them fix your code and make it do what it should have been doing + (also, you often discover your own bugs yourself, while writing the + log message to summarize the thought behind it). + +. Your code may be doing things that were only necessary for your + immediate needs (e.g. "do X to directories" without implementing or + even designing what is to be done on files). Writing down why you + excluded what the code does not do will help guide future developers. + Writing down "we do X to directories, because directories have + characteristic Y" would help them infer "oh, files also have the same + characteristic Y, so perhaps doing X to them would also make sense?". + Saying "we don't do the same X to files, because ..." will help them + decide if the reasoning is sound (in which case they do not waste + time extending your code to cover files), or reason differently (in + which case, they can explain why they extend your code to cover + files, too). + +The goal of your log message is to convey the _why_ behind your +change to help future developers. + The first line of the commit message should be a short description (50 characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), and should skip the full stop. It is also conventional in most cases to @@ -142,6 +171,13 @@ The body should provide a meaningful commit message, which: . alternate solutions considered but discarded, if any. +[[present-tense]] +The problem statement that describes the status quo is written in the +present tense. Write "The code does X when it is given input Y", +instead of "The code used to do Y when given input X". You do not +have to say "Currently"---the status quo in the problem statement is +about the code _without_ your change, by project convention. + [[imperative-mood]] Describe your changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy diff --git a/Documentation/config.txt b/Documentation/config.txt index b168f02dc3..bf3e512921 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -159,6 +159,33 @@ all branches that begin with `foo/`. This is useful if your branches are organized hierarchically and you would like to apply a configuration to all the branches in that hierarchy. +`hasconfig:remote.*.url:`:: + The data that follows this keyword is taken to + be a pattern with standard globbing wildcards and two + additional ones, `**/` and `/**`, that can match multiple + components. The first time this keyword is seen, the rest of + the config files will be scanned for remote URLs (without + applying any values). If there exists at least one remote URL + that matches this pattern, the include condition is met. ++ +Files included by this option (directly or indirectly) are not allowed +to contain remote URLs. ++ +Note that unlike other includeIf conditions, resolving this condition +relies on information that is not yet known at the point of reading the +condition. A typical use case is this option being present as a +system-level or global-level config, and the remote URL being in a +local-level config; hence the need to scan ahead when resolving this +condition. In order to avoid the chicken-and-egg problem in which +potentially-included files can affect whether such files are potentially +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 +a naming scheme that supports more variable-based include conditions, +but currently Git only supports the exact keyword described above. + A few more notes on matching via `gitdir` and `gitdir/i`: * Symlinks in `$GIT_DIR` are not resolved before matching. @@ -226,6 +253,14 @@ Example ; currently checked out [includeIf "onbranch:foo-branch"] path = foo.inc + +; include only if a remote with the given URL exists (note +; that such a URL may be provided later in a file or in a +; file read after this file is read, as seen in this example) +[includeIf "hasconfig:remote.*.url:https://example.com/**"] + path = foo.inc +[remote "origin"] + url = https://example.com/git ---- Values diff --git a/Documentation/config/fetch.txt b/Documentation/config/fetch.txt index 63748c02b7..cd65d236b4 100644 --- a/Documentation/config/fetch.txt +++ b/Documentation/config/fetch.txt @@ -56,18 +56,19 @@ fetch.output:: OUTPUT in linkgit:git-fetch[1] for detail. fetch.negotiationAlgorithm:: - Control how information about the commits in the local repository is - sent when negotiating the contents of the packfile to be sent by the - server. Set to "skipping" to use an algorithm that skips commits in an - effort to converge faster, but may result in a larger-than-necessary - packfile; or set to "noop" to not send any information at all, which - will almost certainly result in a larger-than-necessary packfile, but - will skip the negotiation step. - The default is "default" which instructs Git to use the default algorithm - that never skips commits (unless the server has acknowledged it or one - of its descendants). If `feature.experimental` is enabled, then this - setting defaults to "skipping". - Unknown values will cause 'git fetch' to error out. + Control how information about the commits in the local repository + is sent when negotiating the contents of the packfile to be sent by + the server. Set to "consecutive" to use an algorithm that walks + over consecutive commits checking each one. Set to "skipping" to + use an algorithm that skips commits in an effort to converge + faster, but may result in a larger-than-necessary packfile; or set + to "noop" to not send any information at all, which will almost + certainly result in a larger-than-necessary packfile, but will skip + the negotiation step. Set to "default" to override settings made + previously and use the default behaviour. The default is normally + "consecutive", but if `feature.experimental` is true, then the + default is "skipping". Unknown values will cause 'git fetch' to + error out. + See also the `--negotiate-only` and `--negotiation-tip` options to linkgit:git-fetch[1]. diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt index 0cb189a077..86892ada77 100644 --- a/Documentation/config/gpg.txt +++ b/Documentation/config/gpg.txt @@ -37,7 +37,7 @@ gpg.minTrustLevel:: gpg.ssh.defaultKeyCommand:: This command that will be run when user.signingkey is not set and a ssh signature is requested. On successful exit a valid ssh public key is - expected in the first line of its output. To automatically use the first + expected in the first line of its output. To automatically use the first available key from your ssh-agent set this to "ssh-add -L". gpg.ssh.allowedSignersFile:: @@ -66,7 +66,7 @@ This way only committers with an already valid key can add or change keys in the + Since OpensSSH 8.8 this file allows specifying a key lifetime using valid-after & valid-before options. Git will mark signatures as valid if the signing key was -valid at the time of the signatures creation. This allows users to change a +valid at the time of the signature's creation. This allows users to change a signing key without invalidating all previously made signatures. + Using a SSH CA key with the cert-authority option diff --git a/Documentation/config/stash.txt b/Documentation/config/stash.txt index 9ed775281f..b9f609ed76 100644 --- a/Documentation/config/stash.txt +++ b/Documentation/config/stash.txt @@ -1,10 +1,3 @@ -stash.useBuiltin:: - Unused configuration variable. Used in Git versions 2.22 to - 2.26 as an escape hatch to enable the legacy shellscript - implementation of stash. Now the built-in rewrite of it in C - is always used. Setting this will emit a warning, to alert any - remaining users that setting this now does nothing. - stash.showIncludeUntracked:: If this is set to true, the `git stash show` command will show the untracked files of a stash entry. Defaults to false. See diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index c89d530d3d..3674ac48e9 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -34,7 +34,7 @@ endif::git-diff[] endif::git-format-patch[] ifdef::git-log[] ---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc):: +--diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r):: --no-diff-merges:: Specify diff format to be used for merge commits. Default is {diff-merges-default} unless `--first-parent` is in use, in which case @@ -64,6 +64,18 @@ ifdef::git-log[] each of the parents. Separate log entry and diff is generated for each parent. + +--diff-merges=remerge::: +--diff-merges=r::: +--remerge-diff::: + With this option, two-parent merge commits are remerged to + create a temporary tree object -- potentially containing files + with conflict markers and such. A diff is then shown between + that temporary tree and the actual merge commit. ++ +The output emitted when this option is used is subject to change, and +so is its interaction with other options (unless explicitly +documented). ++ --diff-merges=combined::: --diff-merges=c::: -c::: @@ -616,11 +628,8 @@ ifndef::git-format-patch[] Also, these upper-case letters can be downcased to exclude. E.g. `--diff-filter=ad` excludes added and deleted paths. + -Note that not all diffs can feature all types. For instance, diffs -from the index to the working tree can never have Added entries -(because the set of paths included in the diff is limited by what is in -the index). Similarly, copied and renamed entries cannot appear if -detection for those types is disabled. +Note that not all diffs can feature all types. For instance, copied and +renamed entries cannot appear if detection for those types is disabled. -S<string>:: Look for differences that change the number of occurrences of diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index e967ff1874..f903683189 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -71,6 +71,7 @@ configuration variables documented in linkgit:git-config[1], and the ancestors of the provided `--negotiation-tip=*` arguments, which we have in common with the server. + +This is incompatible with `--recurse-submodules=[yes|on-demand]`. Internally this is used to implement the `push.negotiate` option, see linkgit:git-config[1]. diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 27b27e2b30..bef76f4dd0 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -9,8 +9,14 @@ git-cat-file - Provide content or type and size information for repository objec SYNOPSIS -------- [verse] -'git cat-file' (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv | --filters ) [--path=<path>] <object> -'git cat-file' (--batch[=<format>] | --batch-check[=<format>]) [ --textconv | --filters ] [--follow-symlinks] +'git cat-file' <type> <object> +'git cat-file' (-e | -p) <object> +'git cat-file' (-t | -s) [--allow-unknown-type] <object> +'git cat-file' (--batch | --batch-check) [--batch-all-objects] + [--buffer] [--follow-symlinks] [--unordered] + [--textconv | --filters] +'git cat-file' (--textconv | --filters) + [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>] DESCRIPTION ----------- diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index 0c3924a63d..2892799e32 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -33,7 +33,7 @@ OPTIONS Instead of printing the paths that are excluded, for each path that matches an exclude pattern, print the exclude pattern together with the path. (Matching an exclude pattern usually - means the path is excluded, but if the pattern begins with '!' + means the path is excluded, but if the pattern begins with "`!`" then it is a negated pattern and matching it means the path is NOT excluded.) + @@ -77,7 +77,7 @@ If `--verbose` is specified, the output is a series of lines of the form: <pathname> is the path of a file being queried, <pattern> is the matching pattern, <source> is the pattern's source file, and <linenum> is the line number of the pattern within that source. If the pattern -contained a `!` prefix or `/` suffix, it will be preserved in the +contained a "`!`" prefix or "`/`" suffix, it will be preserved in the output. <source> will be an absolute path when referring to the file configured by `core.excludesFile`, or relative to the repository root when referring to `.git/info/exclude` or a per-directory exclude file. diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 4d33e7be0f..01dbd5cbf5 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=<string>] [--stage=<number>|all] [--temp] + [--ignore-skip-worktree-bits] [-z] [--stdin] [--] [<file>...] @@ -37,8 +38,9 @@ OPTIONS -a:: --all:: - checks out all files in the index. Cannot be used - together with explicit filenames. + checks out all files in the index except for those with the + skip-worktree bit set (see `--ignore-skip-worktree-bits`). + Cannot be used together with explicit filenames. -n:: --no-create:: @@ -59,6 +61,10 @@ OPTIONS write the content to temporary files. The temporary name associations will be written to stdout. +--ignore-skip-worktree-bits:: + Check out all files, including those with the skip-worktree bit + set. + --stdin:: Instead of taking list of paths from the command line, read list of paths from the standard input. Paths are diff --git a/Documentation/git-hook.txt b/Documentation/git-hook.txt new file mode 100644 index 0000000000..77c3a8ad90 --- /dev/null +++ b/Documentation/git-hook.txt @@ -0,0 +1,45 @@ +git-hook(1) +=========== + +NAME +---- +git-hook - Run git hooks + +SYNOPSIS +-------- +[verse] +'git hook' run [--ignore-missing] <hook-name> [-- <hook-args>] + +DESCRIPTION +----------- + +A command interface to running git hooks (see linkgit:githooks[5]), +for use by other scripted git commands. + +SUBCOMMANDS +----------- + +run:: + Run the `<hook-name>` hook. See linkgit:githooks[5] for + supported hook names. ++ + +Any positional arguments to the hook should be passed after a +mandatory `--` (or `--end-of-options`, see linkgit:gitcli[7]). See +linkgit:githooks[5] for arguments hooks might expect (if any). + +OPTIONS +------- + +--ignore-missing:: + Ignore any missing hook by quietly returning zero. Used for + tools that want to do a blind one-shot run of a hook that may + or may not be present. + +SEE ALSO +-------- +linkgit:githooks[5] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index 27fe2b32e1..76b44f4da1 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -31,7 +31,7 @@ OPTIONS --batch:: Allow building of more than one tree object before exiting. Each - tree is separated by as single blank line. The final new-line is + tree is separated by a single blank line. The final new-line is optional. Note - if the `-z` option is used, lines are terminated with NUL. diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index 5cb0eb0855..ec8a27ce8b 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -42,11 +42,37 @@ OPTIONS --all:: List all commits reachable from all refs ---stdin:: +--annotate-stdin:: Transform stdin by substituting all the 40-character SHA-1 hexes (say $hex) with "$hex ($rev_name)". When used with --name-only, substitute with "$rev_name", omitting $hex - altogether. Intended for the scripter's use. + altogether. ++ +For example: ++ +----------- +$ cat sample.txt + +An abbreviated revision 2ae0a9cb82 will not be substituted. +The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907, +while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad + +$ git name-rev --annotate-stdin <sample.txt + +An abbreviated revision 2ae0a9cb82 will not be substituted. +The full name after substitution is 2ae0a9cb8298185a94e5998086f380a355dd8907 (master), +while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad + +$ git name-rev --name-only --annotate-stdin <sample.txt + +An abbreviated revision 2ae0a9cb82 will not be substituted. +The full name after substitution is master, +while its tree object is 70d105cc79e63b81cfdcb08a15297c23e60b07ad +----------- + +--stdin:: + This option is deprecated in favor of 'git name-rev --annotate-stdin'. + They are functionally equivalent. --name-only:: Instead of printing both the SHA-1 and the name, print only diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 83fd4e19a4..60984a4682 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -160,11 +160,12 @@ unspecified. ^^^^^ This attribute sets a specific line-ending style to be used in the -working directory. It enables end-of-line conversion without any -content checks, effectively setting the `text` attribute. Note that -setting this attribute on paths which are in the index with CRLF line -endings may make the paths to be considered dirty. Adding the path to -the index again will normalize the line endings in the index. +working directory. This attribute has effect only if the `text` +attribute is set or unspecified, or if it is set to `auto` and the file +is detected as text. Note that setting this attribute on paths which +are in the index with CRLF line endings may make the paths to be +considered dirty. Adding the path to the index again will normalize the +line endings in the index. Set to string value "crlf":: diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 92e4ba6a2f..1819a5a185 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -19,6 +19,15 @@ Many commands take revisions (most often "commits", but sometimes "tree-ish", depending on the context and command) and paths as their arguments. Here are the rules: + * Options come first and then args. + A subcommand may take dashed options (which may take their own + arguments, e.g. "--max-parents 2") and arguments. You SHOULD + give dashed options first and then arguments. Some commands may + accept dashed options after you have already gave non-option + arguments (which may make the command ambiguous), but you should + not rely on it (because eventually we may find a way to fix + these ambiguity by enforcing the "options then args" rule). + * Revisions come first and then paths. E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`, `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86` @@ -72,24 +81,24 @@ you will. Here are the rules regarding the "flags" that you should follow when you are scripting Git: - * it's preferred to use the non-dashed form of Git commands, which means that + * It's preferred to use the non-dashed form of Git commands, which means that you should prefer `git foo` to `git-foo`. - * splitting short options to separate words (prefer `git foo -a -b` + * Splitting short options to separate words (prefer `git foo -a -b` to `git foo -ab`, the latter may not even work). - * when a command-line option takes an argument, use the 'stuck' form. In + * When a command-line option takes an argument, use the 'stuck' form. In other words, write `git foo -oArg` instead of `git foo -o Arg` for short options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg` for long options. An option that takes optional option-argument must be written in the 'stuck' form. - * when you give a revision parameter to a command, make sure the parameter is + * When you give a revision parameter to a command, make sure the parameter is not ambiguous with a name of a file in the work tree. E.g. do not write `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work if you happen to have a file called `HEAD` in the work tree. - * many commands allow a long option `--option` to be abbreviated + * Many commands allow a long option `--option` to be abbreviated only to their unique prefix (e.g. if there is no other option whose name begins with `opt`, you may be able to spell `--opt` to invoke the `--option` flag), but you should fully spell them out diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index b51959ff94..a16e62bc8c 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -698,6 +698,10 @@ and "0" meaning they were not. Only one parameter should be set to "1" when the hook runs. The hook running passing "1", "1" should not be possible. +SEE ALSO +-------- +linkgit:git-hook[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 43a86fa562..fd4f4e26c9 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -122,19 +122,27 @@ again. Equivalent forms are `--min-parents=0` (any commit has 0 or more parents) and `--max-parents=-1` (negative numbers denote no upper limit). --first-parent:: - Follow only the first parent commit upon seeing a merge - commit. This option can give a better overview when - viewing the evolution of a particular topic branch, - 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. + When finding commits to include, follow only the first + parent commit upon seeing a merge commit. This option + can give a better overview when viewing the evolution of + a particular topic branch, 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. ifdef::git-log[] + This option also changes default diff format for merge commits to `first-parent`, see `--diff-merges=first-parent` for details. endif::git-log[] +--exclude-first-parent-only:: + When finding commits to exclude (with a '{caret}'), follow only + the first parent commit upon seeing a merge commit. + This can be used to find the set of changes in a topic branch + from the point where it diverged from the remote branch, given + that arbitrary merges can be valid topic branch changes. + --not:: Reverses the meaning of the '{caret}' prefix (or lack thereof) for all following revision specifiers, up to the next `--not`. diff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/technical/multi-pack-index.txt index b39c69da8c..f2221d2b44 100644 --- a/Documentation/technical/multi-pack-index.txt +++ b/Documentation/technical/multi-pack-index.txt @@ -24,6 +24,7 @@ and their offsets into multiple packfiles. It contains: ** An offset within the jth packfile for the object. * If large offsets are required, we use another list of large offsets similar to version 2 pack-indexes. +- An optional list of objects in pseudo-pack order (used with MIDX bitmaps). Thus, we can provide O(log N) lookup time for any number of packfiles. diff --git a/Documentation/technical/pack-format.txt b/Documentation/technical/pack-format.txt index 8d2f42f29e..6d3efb7d16 100644 --- a/Documentation/technical/pack-format.txt +++ b/Documentation/technical/pack-format.txt @@ -376,6 +376,11 @@ CHUNK DATA: [Optional] Object Large Offsets (ID: {'L', 'O', 'F', 'F'}) 8-byte offsets into large packfiles. + [Optional] Bitmap pack order (ID: {'R', 'I', 'D', 'X'}) + A list of MIDX positions (one per object in the MIDX, num_objects in + total, each a 4-byte unsigned integer in network byte order), sorted + according to their relative bitmap/pseudo-pack positions. + TRAILER: Index checksum of the above contents. @@ -456,9 +461,5 @@ In short, a MIDX's pseudo-pack is the de-duplicated concatenation of objects in packs stored by the MIDX, laid out in pack order, and the packs arranged in MIDX order (with the preferred pack coming first). -Finally, note that the MIDX's reverse index is not stored as a chunk in -the multi-pack-index itself. This is done because the reverse index -includes the checksum of the pack or MIDX to which it belongs, which -makes it impossible to write in the MIDX. To avoid races when rewriting -the MIDX, a MIDX reverse index includes the MIDX's checksum in its -filename (e.g., `multi-pack-index-xyz.rev`). +The MIDX's reverse index is stored in the optional 'RIDX' chunk within +the MIDX itself. |