diff options
Diffstat (limited to 'Documentation')
30 files changed, 400 insertions, 147 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 9022d48355..1c3771e7d7 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -14,4 +14,5 @@ manpage-base-url.xsl SubmittingPatches.txt tmp-doc-diff/ GIT-ASCIIDOCFLAGS +/.build/ /GIT-EXCLUDED-PROGRAMS diff --git a/Documentation/Makefile b/Documentation/Makefile index f5605b7767..911b6bf79c 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -90,6 +90,7 @@ SP_ARTICLES += $(API_DOCS) TECH_DOCS += MyFirstContribution TECH_DOCS += MyFirstObjectWalk TECH_DOCS += SubmittingPatches +TECH_DOCS += technical/bundle-format TECH_DOCS += technical/hash-function-transition TECH_DOCS += technical/http-protocol TECH_DOCS += technical/index-format @@ -225,6 +226,7 @@ endif ifneq ($(findstring $(MAKEFLAGS),s),s) ifndef V + QUIET = @ QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@; QUIET_XMLTO = @echo ' ' XMLTO $@; QUIET_DB2TEXI = @echo ' ' DB2TEXI $@; @@ -232,11 +234,15 @@ ifndef V QUIET_DBLATEX = @echo ' ' DBLATEX $@; QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; QUIET_GEN = @echo ' ' GEN $@; - QUIET_LINT = @echo ' ' LINT $@; QUIET_STDERR = 2> /dev/null QUIET_SUBDIR0 = +@subdir= QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ $(MAKE) $(PRINT_DIR) -C $$subdir + + QUIET_LINT_GITLINK = @echo ' ' LINT GITLINK $<; + QUIET_LINT_MANSEC = @echo ' ' LINT MAN SEC $<; + QUIET_LINT_MANEND = @echo ' ' LINT MAN END $<; + export V endif endif @@ -284,7 +290,7 @@ install-html: html ../GIT-VERSION-FILE: FORCE $(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE -ifneq ($(MAKECMDGOALS),clean) +ifneq ($(filter-out lint-docs clean,$(MAKECMDGOALS)),) -include ../GIT-VERSION-FILE endif @@ -343,6 +349,7 @@ GIT-ASCIIDOCFLAGS: FORCE fi clean: + $(RM) -rf .build/ $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 $(RM) *.texi *.texi+ *.texi++ git.info gitman.info $(RM) *.pdf @@ -456,14 +463,61 @@ quick-install-html: require-htmlrepo print-man1: @for i in $(MAN1_TXT); do echo $$i; done -lint-docs:: - $(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \ +## Lint: Common +.build: + $(QUIET)mkdir $@ +.build/lint-docs: | .build + $(QUIET)mkdir $@ + +## Lint: gitlink +.build/lint-docs/gitlink: | .build/lint-docs + $(QUIET)mkdir $@ +.build/lint-docs/gitlink/howto: | .build/lint-docs + $(QUIET)mkdir $@ +.build/lint-docs/gitlink/config: | .build/lint-docs + $(QUIET)mkdir $@ +LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT)) +$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink +$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink/howto +$(LINT_DOCS_GITLINK): | .build/lint-docs/gitlink/config +$(LINT_DOCS_GITLINK): lint-gitlink.perl +$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt + $(QUIET_LINT_GITLINK)$(PERL_PATH) lint-gitlink.perl \ + $< \ $(HOWTO_TXT) $(DOC_DEP_TXT) \ --section=1 $(MAN1_TXT) \ --section=5 $(MAN5_TXT) \ - --section=7 $(MAN7_TXT); \ - $(PERL_PATH) lint-man-end-blurb.perl $(MAN_TXT); \ - $(PERL_PATH) lint-man-section-order.perl $(MAN_TXT); + --section=7 $(MAN7_TXT) >$@ +.PHONY: lint-docs-gitlink +lint-docs-gitlink: $(LINT_DOCS_GITLINK) + +## Lint: man-end-blurb +.build/lint-docs/man-end-blurb: | .build/lint-docs + $(QUIET)mkdir $@ +LINT_DOCS_MAN_END_BLURB = $(patsubst %.txt,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT)) +$(LINT_DOCS_MAN_END_BLURB): | .build/lint-docs/man-end-blurb +$(LINT_DOCS_MAN_END_BLURB): lint-man-end-blurb.perl +$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.txt + $(QUIET_LINT_MANEND)$(PERL_PATH) lint-man-end-blurb.perl $< >$@ +.PHONY: lint-docs-man-end-blurb +lint-docs-man-end-blurb: $(LINT_DOCS_MAN_END_BLURB) + +## Lint: man-section-order +.build/lint-docs/man-section-order: | .build/lint-docs + $(QUIET)mkdir $@ +LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.txt,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT)) +$(LINT_DOCS_MAN_SECTION_ORDER): | .build/lint-docs/man-section-order +$(LINT_DOCS_MAN_SECTION_ORDER): lint-man-section-order.perl +$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt + $(QUIET_LINT_MANSEC)$(PERL_PATH) lint-man-section-order.perl $< >$@ +.PHONY: lint-docs-man-section-order +lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER) + +## Lint: list of targets above +.PHONY: lint-docs +lint-docs: lint-docs-gitlink +lint-docs: lint-docs-man-end-blurb +lint-docs: lint-docs-man-section-order ifeq ($(wildcard po/Makefile),po/Makefile) doc-l10n install-l10n:: diff --git a/Documentation/RelNotes/2.34.0.txt b/Documentation/RelNotes/2.34.0.txt index 080687f202..fdf7992193 100644 --- a/Documentation/RelNotes/2.34.0.txt +++ b/Documentation/RelNotes/2.34.0.txt @@ -4,6 +4,11 @@ Git 2.34 Release Notes Updates since Git 2.33 ---------------------- +Backward compatibility notes + + * The "--preserve-merges" option of "git rebase" has been removed. + + UI, Workflows & Features * Pathname expansion (like "~username/") learned a way to specify a @@ -62,6 +67,18 @@ UI, Workflows & Features * The ref iteration code used to optionally allow dangling refs to be shown, which has been tightened up. + * "git add", "git mv", and "git rm" have been adjusted to avoid + updating paths outside of the sparse-checkout definition unless + the user specifies a "--sparse" option. + + * "git repack" has been taught to generate multi-pack reachability + bitmaps. + + * "git fsck" has been taught to report mismatch between expected and + actual types of an object better. + + * Use ssh public crypto for object and push-cert signing. + Performance, Internal Implementation, Development Support etc. @@ -146,6 +163,26 @@ Performance, Internal Implementation, Development Support etc. * CI learns to run the leak sanitizer builds. + * "git grep --recurse-submodules" takes trees and blobs from the + submodule repository, but the textconv settings when processing a + blob from the submodule is not taken from the submodule repository. + A test is added to demonstrate the issue, without fixing it. + + * Teach "git help -c" into helping the command line completion of + configuration variables. + + * When "git cmd -h" shows more than one line of usage text (e.g. + the cmd subcommand may take sub-sub-command), parse-options API + learned to align these lines, even across i18n/l10n. + + * Prevent "make sparse" from running for the source files that + haven't been modified. + + * The codepath to write a new version of .midx multi-pack index files + has learned to release the mmaped memory holding the current + version of .midx before removing them from the disk, as some + platforms do not allow removal of a file that still has mapping. + Fixes since v2.33 ----------------- @@ -275,6 +312,62 @@ Fixes since v2.33 * Protocol v0 clients can get stuck parsing a malformed feature line. + * A few kinds of changes "git status" can show were not documented. + (merge d2a534c515 ja/doc-status-types-and-copies later to maint). + + * The mergesort implementation used to sort linked list has been + optimized. + (merge c90cfc225b rs/mergesort later to maint). + + * An editor session launched during a Git operation (e.g. during 'git + commit') can leave the terminal in a funny state. The code path + has updated to save the terminal state before, and restore it + after, it spawns an editor. + (merge 3d411afabc cm/save-restore-terminal later to maint). + + * "git cat-file --batch" with the "--batch-all-objects" option is + supposed to iterate over all the objects found in a repository, but + it used to translate these object names using the replace mechanism, + which defeats the point of enumerating all objects in the repository. + This has been corrected. + (merge bf972896d7 jk/cat-file-batch-all-wo-replace later to maint). + + * Recent sparse-index work broke safety against attempts to add paths + with trailing slashes to the index, which has been corrected. + (merge c8ad9d04c6 rs/make-verify-path-really-verify-again later to maint). + + * The "--color-lines" and "--color-by-age" options of "git blame" + have been missing, which are now documented. + (merge 8c32856133 bs/doc-blame-color-lines later to maint). + + * The PATH used in CI job may be too wide and let incompatible dlls + to be grabbed, which can cause the build&test to fail. Tighten it. + (merge 7491ef6198 js/windows-ci-path-fix later to maint). + + * Avoid performance measurements from getting ruined by gc and other + housekeeping pauses interfering in the middle. + (merge be79131a53 rs/disable-gc-during-perf-tests later to maint). + + * Stop "git add --dry-run" from creating new blob and tree objects. + (merge e578d0311d rs/add-dry-run-without-objects later to maint). + + * "git commit" gave duplicated error message when the object store + was unwritable, which has been corrected. + (merge 4ef91a2d79 ab/fix-commit-error-message-upon-unwritable-object-store later to maint). + + * Recent sparse-index addition, namely any use of index_name_pos(), + can expand sparse index entries and breaks any code that walks + cache-tree or existing index entries. One such instance of such a + breakage has been corrected. + + * The xxdiff difftool backend can exit with status 128, which the + difftool-helper that launches the backend takes as a significant + failure, when it is not significant at all. Work it around. + (merge 571f4348dd da/mergetools-special-case-xxdiff-exit-128 later to maint). + + * Improve test framework around unwritable directories. + (merge 5d22e18965 ab/test-cleanly-recreate-trash-directory later to maint). + * Other code cleanup, docfix, build fix, etc. (merge f188160be9 ab/bundle-remove-verbose-option later to maint). (merge 8c6b4332b4 rs/close-pack-leakfix later to maint). @@ -283,3 +376,8 @@ Fixes since v2.33 (merge 6ffb990dc4 os/status-docfix later to maint). (merge 100c2da2d3 rs/p3400-lose-tac later to maint). (merge 76f3b69896 tb/aggregate-ignore-leading-whitespaces later to maint). + (merge 6e4fd8bfcd tz/doc-link-to-bundle-format-fix later to maint). + (merge f6c013dfa1 jc/doc-commit-header-continuation-line later to maint). + (merge ec9a37d69b ab/pkt-line-cleanup later to maint). + (merge 8650c6298c ab/fix-make-lint-docs later to maint). + (merge 1c720357ce ab/test-lib-diff-cleanup later to maint). diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 117f4cf806..9a663535f4 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -136,5 +136,16 @@ take effect. option. An empty file name, `""`, will clear the list of revs from previously processed files. +--color-lines:: + Color line annotations in the default format differently if they come from + the same commit as the preceding line. This makes it easier to distinguish + code blocks introduced by different commits. The color defaults to cyan and + can be adjusted using the `color.blame.repeatedLines` config option. + +--color-by-age:: + Color line annotations depending on the age of the line in the default format. + The `color.blame.highlightRecent` config option controls what color is used for + each range of age. + -h:: Show help message. diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt index cc5f3249fc..d323d7327f 100644 --- a/Documentation/config/branch.txt +++ b/Documentation/config/branch.txt @@ -85,10 +85,6 @@ When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase' so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When `preserve` (or just 'p', deprecated in favor of `merges`), also pass -`--preserve-merges` along to 'git rebase' so that locally committed merge -commits will not be flattened by running 'git pull'. -+ When the value is `interactive` (or just 'i'), the rebase is run in interactive mode. + diff --git a/Documentation/config/color.txt b/Documentation/config/color.txt index e05d520a86..6e817f6047 100644 --- a/Documentation/config/color.txt +++ b/Documentation/config/color.txt @@ -9,26 +9,27 @@ color.advice.hint:: Use customized color for hints. color.blame.highlightRecent:: - This can be used to color the metadata of a blame line depending - on age of the line. + Specify the line annotation color for `git blame --color-by-age` + depending upon the age of the line. + -This setting should be set to a comma-separated list of color and date settings, -starting and ending with a color, the dates should be set from oldest to newest. -The metadata will be colored given the colors if the line was introduced -before the given timestamp, overwriting older timestamped colors. +This setting should be set to a comma-separated list of color and +date settings, starting and ending with a color, the dates should be +set from oldest to newest. The metadata will be colored with the +specified colors if the line was introduced before the given +timestamp, overwriting older timestamped colors. + -Instead of an absolute timestamp relative timestamps work as well, e.g. -2.weeks.ago is valid to address anything older than 2 weeks. +Instead of an absolute timestamp relative timestamps work as well, +e.g. `2.weeks.ago` is valid to address anything older than 2 weeks. + -It defaults to 'blue,12 month ago,white,1 month ago,red', which colors -everything older than one year blue, recent changes between one month and -one year old are kept white, and lines introduced within the last month are -colored red. +It defaults to `blue,12 month ago,white,1 month ago,red`, which +colors everything older than one year blue, recent changes between +one month and one year old are kept white, and lines introduced +within the last month are colored red. color.blame.repeatedLines:: - Use the customized color for the part of git-blame output that - is repeated meta information per line (such as commit id, - author name, date and timezone). Defaults to cyan. + Use the specified color to colorize line annotations for + `git blame --color-lines`, if they come from the same commit as the + preceding line. Defaults to cyan. color.branch:: A boolean to enable/disable color in the output of diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt index d94025cb36..4f30c7dbdd 100644 --- a/Documentation/config/gpg.txt +++ b/Documentation/config/gpg.txt @@ -11,13 +11,13 @@ gpg.program:: gpg.format:: Specifies which key format to use when signing with `--gpg-sign`. - Default is "openpgp" and another possible value is "x509". + Default is "openpgp". Other possible values are "x509", "ssh". gpg.<format>.program:: Use this to customize the program used for the signing format you chose. (see `gpg.program` and `gpg.format`) `gpg.program` can still be used as a legacy synonym for `gpg.openpgp.program`. The default - value for `gpg.x509.program` is "gpgsm". + value for `gpg.x509.program` is "gpgsm" and `gpg.ssh.program` is "ssh-keygen". gpg.minTrustLevel:: Specifies a minimum trust level for signature verification. If @@ -33,3 +33,42 @@ gpg.minTrustLevel:: * `marginal` * `fully` * `ultimate` + +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 + available key from your ssh-agent set this to "ssh-add -L". + +gpg.ssh.allowedSignersFile:: + A file containing ssh public keys which you are willing to trust. + The file consists of one or more lines of principals followed by an ssh + public key. + e.g.: user1@example.com,user2@example.com ssh-rsa AAAAX1... + See ssh-keygen(1) "ALLOWED SIGNERS" for details. + The principal is only used to identify the key and is available when + verifying a signature. ++ +SSH has no concept of trust levels like gpg does. To be able to differentiate +between valid signatures and trusted signatures the trust level of a signature +verification is set to `fully` when the public key is present in the allowedSignersFile. +Otherwise the trust level is `undefined` and git verify-commit/tag will fail. ++ +This file can be set to a location outside of the repository and every developer +maintains their own trust store. A central repository server could generate this +file automatically from ssh keys with push access to verify the code against. +In a corporate setting this file is probably generated at a global location +from automation that already handles developer ssh keys. ++ +A repository that only allows signed commits can store the file +in the repository itself using a path relative to the top-level of the working tree. +This way only committers with an already valid key can add or change keys in the keyring. ++ +Using a SSH CA key with the cert-authority option +(see ssh-keygen(1) "CERTIFICATES") is also valid. + +gpg.ssh.revocationFile:: + Either a SSH KRL or a list of revoked public keys (without the principal prefix). + See ssh-keygen(1) for details. + If a public key is found in this file then it will always be treated + as having trust level "never" and signatures will show as invalid. diff --git a/Documentation/config/pull.txt b/Documentation/config/pull.txt index 5404830609..9349e09261 100644 --- a/Documentation/config/pull.txt +++ b/Documentation/config/pull.txt @@ -18,10 +18,6 @@ When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase' so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When `preserve` (or just 'p', deprecated in favor of `merges`), also pass -`--preserve-merges` along to 'git rebase' so that locally committed merge -commits will not be flattened by running 'git pull'. -+ When the value is `interactive` (or just 'i'), the rebase is run in interactive mode. + diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt index 59aec7c3ae..ad78dce9ec 100644 --- a/Documentation/config/user.txt +++ b/Documentation/config/user.txt @@ -36,3 +36,10 @@ user.signingKey:: commit, you can override the default selection with this variable. This option is passed unchanged to gpg's --local-user parameter, so you may specify a key using any method that gpg supports. + If gpg.format is set to "ssh" this can contain the literal ssh public + key (e.g.: "ssh-rsa XXXXXX identifier") or a file which contains it and + corresponds to the private key used for signing. The private key + needs to be available via ssh-agent. Alternatively it can be set to + a file containing a private key directly. If not set git will call + gpg.ssh.defaultKeyCommand (e.g.: "ssh-add -L") and try to use the first + key available. diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index fbbd410a84..7a9c3b6ff4 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -59,7 +59,7 @@ Possible status letters are: - D: deletion of a file - M: modification of the contents or mode of a file - R: renaming of a file -- T: change in the type of the file +- T: change in the type of the file (regular file, symbolic link or submodule) - U: file is unmerged (you must complete the merge before it can be committed) - X: "unknown" change type (most probably a bug, please report it) diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index be5e3ac54b..11eb70f16c 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] - [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] + [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]] [--sparse] [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize] [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...] @@ -79,6 +79,13 @@ in linkgit:gitglossary[7]. --force:: Allow adding otherwise ignored files. +--sparse:: + Allow updating index entries outside of the sparse-checkout cone. + Normally, `git add` refuses to update index entries whose paths do + not fit within the sparse-checkout cone, since those files might + be removed from the working tree without warning. See + linkgit:git-sparse-checkout[1] for more details. + -i:: --interactive:: Add modified contents in the working tree interactively to diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 3bf5d5d8b4..d7a46cc674 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -11,8 +11,8 @@ SYNOPSIS 'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--ignore-rev <rev>] [--ignore-revs-file <file>] - [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>..<rev>] - [--] <file> + [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>] + [<rev> | --contents <file> | --reverse <rev>..<rev>] [--] <file> DESCRIPTION ----------- @@ -93,6 +93,19 @@ include::blame-options.txt[] is used for a caret to mark the boundary commit. +THE DEFAULT FORMAT +------------------ + +When neither `--porcelain` nor `--incremental` option is specified, +`git blame` will output annotation for each line with: + +- abbreviated object name for the commit the line came from; +- author ident (by default author name and date, unless `-s` or `-e` + is specified); and +- line number + +before the line contents. + THE PORCELAIN FORMAT -------------------- diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 4eb0421b3f..27b27e2b30 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -94,8 +94,10 @@ OPTIONS Instead of reading a list of objects on stdin, perform the requested batch operation on all objects in the repository and any alternate object stores (not just reachable objects). - Requires `--batch` or `--batch-check` be specified. Note that - the objects are visited in order sorted by their hashes. + Requires `--batch` or `--batch-check` be specified. By default, + the objects are visited in order sorted by their hashes; see + also `--unordered` below. Objects are presented as-is, without + respecting the "replace" mechanism of linkgit:git-replace[1]. --buffer:: Normally batch output is flushed after each object is output, so diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index b1a6fe4499..d473c9bf38 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -118,8 +118,9 @@ OPTIONS -f:: --force:: When switching branches, proceed even if the index or the - working tree differs from `HEAD`. This is used to throw away - local changes. + working tree differs from `HEAD`, and even if there are untracked + files in the way. This is used to throw away local changes and + any untracked files or directories that are in the way. + When checking out paths from the index, do not fail upon unmerged entries; instead, unmerged entries are ignored. diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 44fe8860b3..96d5f598b4 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -8,8 +8,10 @@ git-help - Display help information about Git SYNOPSIS -------- [verse] -'git help' [-a|--all [--[no-]verbose]] [-g|--guides] - [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE] +'git help' [-a|--all [--[no-]verbose]] + [[-i|--info] [-m|--man] [-w|--web]] [COMMAND|GUIDE] +'git help' [-g|--guides] +'git help' [-c|--config] DESCRIPTION ----------- @@ -58,8 +60,7 @@ OPTIONS -g:: --guides:: - Prints a list of the Git concept guides on the standard output. This - option overrides any given command or guide name. + Prints a list of the Git concept guides on the standard output. -i:: --info:: diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt index 3b0b55cd75..b008ce2850 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -45,6 +45,25 @@ write:: --[no-]bitmap:: Control whether or not a multi-pack bitmap is written. + + --stdin-packs:: + Write a multi-pack index containing only the set of + line-delimited pack index basenames provided over stdin. + + --refs-snapshot=<path>:: + With `--bitmap`, optionally specify a file which + contains a "refs snapshot" taken prior to repacking. ++ +A reference snapshot is composed of line-delimited OIDs corresponding to +the reference tips, usually taken by `git repack` prior to generating a +new pack. A line may optionally start with a `+` character to indicate +that the reference which corresponds to that OID is "preferred" (see +linkgit:git-config[1]'s `pack.preferBitmapTips`.) ++ +The file given at `<path>` is expected to be readable, and can contain +duplicates. (If a given OID is given more than once, it is marked as +preferred if at least one instance of it begins with the special `+` +marker). -- verify:: diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index aef757ec89..0e14f8b5b2 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -105,7 +105,7 @@ Options related to merging include::merge-options.txt[] -r:: ---rebase[=false|true|merges|preserve|interactive]:: +--rebase[=false|true|merges|interactive]:: When true, rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding to the upstream branch and the upstream branch @@ -116,10 +116,6 @@ When set to `merges`, rebase using `git rebase --rebase-merges` so that the local merge commits are included in the rebase (see linkgit:git-rebase[1] for details). + -When set to `preserve` (deprecated in favor of `merges`), rebase with the -`--preserve-merges` option passed to `git rebase` so that locally created -merge commits will not be flattened. -+ When false, merge the upstream branch into the current branch. + When `interactive`, enable the interactive mode of rebase. diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 5fa8bab64c..8c3aceb832 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -10,8 +10,7 @@ SYNOPSIS -------- [verse] 'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] - [-u [--exclude-per-directory=<gitignore>] | -i]] - [--index-output=<file>] [--no-sparse-checkout] + [-u | -i]] [--index-output=<file>] [--no-sparse-checkout] (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]]) @@ -39,8 +38,9 @@ OPTIONS --reset:: Same as -m, except that unmerged entries are discarded instead - of failing. When used with `-u`, updates leading to loss of - working tree changes will not abort the operation. + of failing. When used with `-u`, updates leading to loss of + working tree changes or untracked files or directories will not + abort the operation. -u:: After a successful merge, update the files in the work @@ -88,21 +88,6 @@ OPTIONS The command will refuse to overwrite entries that already existed in the original index file. ---exclude-per-directory=<gitignore>:: - When running the command with `-u` and `-m` options, the - merge result may need to overwrite paths that are not - tracked in the current branch. The command usually - refuses to proceed with the merge to avoid losing such a - path. However this safety valve sometimes gets in the - way. For example, it often happens that the other - branch added a file that used to be a generated file in - your branch, and the safety valve triggers when you try - to switch to that branch after you ran `make` but before - running `make clean` to remove the generated file. This - option tells the command to read per-directory exclude - file (usually '.gitignore') and allows such an untracked - but explicitly ignored file to be overwritten. - --index-output=<file>:: Instead of writing the results out to `$GIT_INDEX_FILE`, write the resulting index in the named file. While the diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index c116dbf4bb..a1af21fcef 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -527,29 +527,12 @@ i.e. commits that would be excluded by linkgit:git-log[1]'s the `rebase-cousins` mode is turned on, such commits are instead rebased onto `<upstream>` (or `<onto>`, if specified). + -The `--rebase-merges` mode is similar in spirit to the deprecated -`--preserve-merges` but works with interactive rebases, -where commits can be reordered, inserted and dropped at will. -+ It is currently only possible to recreate the merge commits using the `ort` merge strategy; different merge strategies can be used only via explicit `exec git merge -s <strategy> [...]` commands. + See also REBASING MERGES and INCOMPATIBLE OPTIONS below. --p:: ---preserve-merges:: - [DEPRECATED: use `--rebase-merges` instead] Recreate merge commits - instead of flattening the history by replaying commits a merge commit - introduces. Merge conflict resolutions or manual amendments to merge - commits are not preserved. -+ -This uses the `--interactive` machinery internally, but combining it -with the `--interactive` option explicitly is generally not a good -idea unless you know what you are doing (see BUGS below). -+ -See also INCOMPATIBLE OPTIONS below. - -x <cmd>:: --exec <cmd>:: Append "exec <cmd>" after each line creating a commit in the @@ -581,9 +564,6 @@ See also INCOMPATIBLE OPTIONS below. the root commit(s) on a branch. When used with --onto, it will skip changes already contained in <newbase> (instead of <upstream>) whereas without --onto it will operate on every change. - When used together with both --onto and --preserve-merges, - 'all' root commits will be rewritten to have <newbase> as parent - instead. + See also INCOMPATIBLE OPTIONS below. @@ -645,7 +625,6 @@ are incompatible with the following options: * --allow-empty-message * --[no-]autosquash * --rebase-merges - * --preserve-merges * --interactive * --exec * --no-keep-empty @@ -656,13 +635,6 @@ are incompatible with the following options: In addition, the following pairs of options are incompatible: - * --preserve-merges and --interactive - * --preserve-merges and --signoff - * --preserve-merges and --rebase-merges - * --preserve-merges and --empty= - * --preserve-merges and --ignore-whitespace - * --preserve-merges and --committer-date-is-author-date - * --preserve-merges and --ignore-date * --keep-base and --onto * --keep-base and --root * --fork-point and --root @@ -1280,29 +1252,6 @@ CONFIGURATION include::config/rebase.txt[] include::config/sequencer.txt[] -BUGS ----- -The todo list presented by the deprecated `--preserve-merges --interactive` -does not represent the topology of the revision graph (use `--rebase-merges` -instead). Editing commits and rewording their commit messages should work -fine, but attempts to reorder commits tend to produce counterintuitive results. -Use `--rebase-merges` in such scenarios instead. - -For example, an attempt to rearrange ------------- -1 --- 2 --- 3 --- 4 --- 5 ------------- -to ------------- -1 --- 2 --- 4 --- 3 --- 5 ------------- -by moving the "pick 4" line will result in the following history: ------------- - 3 - / -1 --- 2 --- 4 --- 5 ------------- - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 24c00c9384..7183fb498f 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -9,7 +9,7 @@ git-repack - Pack unpacked objects in a repository SYNOPSIS -------- [verse] -'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] +'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [-b] [-m] [--window=<n>] [--depth=<n>] [--threads=<n>] [--keep-pack=<pack-name>] [--write-midx] DESCRIPTION ----------- @@ -128,10 +128,11 @@ depth is 4095. -b:: --write-bitmap-index:: Write a reachability bitmap index as part of the repack. This - only makes sense when used with `-a` or `-A`, as the bitmaps + only makes sense when used with `-a`, `-A` or `-m`, as the bitmaps must be able to refer to all reachable objects. This option - overrides the setting of `repack.writeBitmaps`. This option - has no effect if multiple packfiles are created. + overrides the setting of `repack.writeBitmaps`. This option + has no effect if multiple packfiles are created, unless writing a + MIDX (in which case a multi-pack bitmap is created). --pack-kept-objects:: Include objects in `.keep` files when repacking. Note that we @@ -189,6 +190,15 @@ this "roll-up", without respect to their reachability. This is subject to change in the future. This option (implying a drastically different repack mode) is not guaranteed to work with all other combinations of option to `git repack`. ++ +When writing a multi-pack bitmap, `git repack` selects the largest resulting +pack as the preferred pack for object selection by the MIDX (see +linkgit:git-multi-pack-index[1]). + +-m:: +--write-midx:: + Write a multi-pack index (see linkgit:git-multi-pack-index[1]) + containing the non-redundant packs. CONFIGURATION ------------- diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 252e2d4e47..6f7685f53d 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -69,7 +69,8 @@ linkgit:git-add[1]). --hard:: Resets the index and working tree. Any changes to tracked files in the - working tree since `<commit>` are discarded. + working tree since `<commit>` are discarded. Any untracked files or + directories in the way of writing any tracked files are simply deleted. --merge:: Resets the index and updates the files in the working tree that are diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 26e9b28470..81bc23f3cd 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -72,6 +72,12 @@ For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. --ignore-unmatch:: Exit with a zero status even if no files matched. +--sparse:: + Allow updating index entries outside of the sparse-checkout cone. + Normally, `git rm` refuses to update index entries whose paths do + not fit within the sparse-checkout cone. See + linkgit:git-sparse-checkout[1] for more. + -q:: --quiet:: `git rm` normally outputs one line (in the form of an `rm` command) diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 44fd146b91..be41f11974 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -9,10 +9,10 @@ git-send-pack - Push objects over Git protocol to another repository SYNOPSIS -------- [verse] -'git send-pack' [--all] [--dry-run] [--force] [--receive-pack=<git-receive-pack>] +'git send-pack' [--dry-run] [--force] [--receive-pack=<git-receive-pack>] [--verbose] [--thin] [--atomic] [--[no-]signed|--signed=(true|false|if-asked)] - [<host>:]<directory> [<ref>...] + [<host>:]<directory> (--all | <ref>...) DESCRIPTION ----------- diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index c33a3d8d53..4a2c3e0408 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -207,26 +207,29 @@ show tracked paths: * ' ' = unmodified * 'M' = modified +* 'T' = file type changed (regular file, symbolic link or submodule) * 'A' = added * 'D' = deleted * 'R' = renamed -* 'C' = copied +* 'C' = copied (if config option status.renames is set to "copies") * 'U' = updated but unmerged .... X Y Meaning ------------------------------------------------- [AMD] not updated -M [ MD] updated in index -A [ MD] added to index +M [ MTD] updated in index +T [ MTD] type changed in index +A [ MTD] added to index D deleted from index -R [ MD] renamed in index -C [ MD] copied in index -[MARC] index and work tree matches -[ MARC] M work tree changed since index -[ MARC] D deleted in work tree -[ D] R renamed in work tree -[ D] C copied in work tree +R [ MTD] renamed in index +C [ MTD] copied in index +[MTARC] index and work tree matches +[ MTARC] M work tree changed since index +[ MTARC] T type changed in work tree since index +[ MTARC] D deleted in work tree + R renamed in work tree + C copied in work tree ------------------------------------------------- D D unmerged, both deleted A U unmerged, added by us diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index d5776ffcfd..222b556d7a 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -678,7 +678,6 @@ config key: svn.authorsProg --strategy=<strategy>:: -p:: --rebase-merges:: ---preserve-merges (DEPRECATED):: These are only used with the 'dcommit' and 'rebase' commands. + Passed directly to 'git rebase' when using 'dcommit' if a diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl index b22a367844..1c61dd9512 100755 --- a/Documentation/lint-gitlink.perl +++ b/Documentation/lint-gitlink.perl @@ -5,11 +5,12 @@ use warnings; # Parse arguments, a simple state machine for input like: # -# howto/*.txt config/*.txt --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...] +# <file-to-check.txt> <valid-files-to-link-to> --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...] my %TXT; my %SECTION; my $section; my $lint_these = 0; +my $to_check = shift @ARGV; for my $arg (@ARGV) { if (my ($sec) = $arg =~ /^--section=(\d+)$/s) { $section = $sec; @@ -30,13 +31,14 @@ sub report { my ($pos, $line, $target, $msg) = @_; substr($line, $pos) = "' <-- HERE"; $line =~ s/^\s+//; - print "$ARGV:$.: error: $target: $msg, shown with 'HERE' below:\n"; - print "$ARGV:$.:\t'$line\n"; + print STDERR "$ARGV:$.: error: $target: $msg, shown with 'HERE' below:\n"; + print STDERR "$ARGV:$.:\t'$line\n"; $exit_code = 1; } @ARGV = sort values %TXT; -die "BUG: Nothing to process!" unless @ARGV; +die "BUG: No list of valid linkgit:* files given" unless @ARGV; +@ARGV = $to_check; while (<>) { my $line = $_; while ($line =~ m/linkgit:((.*?)\[(\d)\])/g) { diff --git a/Documentation/lint-man-end-blurb.perl b/Documentation/lint-man-end-blurb.perl index d69312e5db..6bdb13ad9f 100755 --- a/Documentation/lint-man-end-blurb.perl +++ b/Documentation/lint-man-end-blurb.perl @@ -6,7 +6,7 @@ use warnings; my $exit_code = 0; sub report { my ($target, $msg) = @_; - print "error: $target: $msg\n"; + print STDERR "error: $target: $msg\n"; $exit_code = 1; } diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl index b05f9156dd..425377dfeb 100755 --- a/Documentation/lint-man-section-order.perl +++ b/Documentation/lint-man-section-order.perl @@ -46,7 +46,7 @@ my $SECTION_RX = do { my $exit_code = 0; sub report { my ($msg) = @_; - print "$ARGV:$.: $msg\n"; + print STDERR "$ARGV:$.: $msg\n"; $exit_code = 1; } diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index b9f3198fbe..ef7fe02a8f 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -613,6 +613,46 @@ stopping after the waitpid() and includes OS process creation overhead). So this time will be slightly larger than the atexit time reported by the child process itself. +`"child_ready"`:: + This event is generated after the current process has started + a background process and released all handles to it. ++ +------------ +{ + "event":"child_ready", + ... + "child_id":2, + "pid":14708, # child PID + "ready":"ready", # child ready state + "t_rel":0.110605 # observed run-time of child process +} +------------ ++ +Note that the session-id of the child process is not available to +the current/spawning process, so the child's PID is reported here as +a hint for post-processing. (But it is only a hint because the child +process may be a shell script which doesn't have a session-id.) ++ +This event is generated after the child is started in the background +and given a little time to boot up and start working. If the child +startups normally and while the parent is still waiting, the "ready" +field will have the value "ready". +If the child is too slow to start and the parent times out, the field +will have the value "timeout". +If the child starts but the parent is unable to probe it, the field +will have the value "error". ++ +After the parent process emits this event, it will release all of its +handles to the child process and treat the child as a background +daemon. So even if the child does eventually finish booting up, +the parent will not emit an updated event. ++ +Note that the `t_rel` field contains the observed run time in seconds +when the parent released the child process into the background. +The child is assumed to be a long-running daemon process and may +outlive the parent process. So the parent's child event times should +not be compared to the child's atexit times. + `"exec"`:: This event is generated before git attempts to `exec()` another command rather than starting a child process. diff --git a/Documentation/technical/signature-format.txt b/Documentation/technical/signature-format.txt index 2c9406a56a..166721be6f 100644 --- a/Documentation/technical/signature-format.txt +++ b/Documentation/technical/signature-format.txt @@ -13,6 +13,22 @@ Signatures always begin with `-----BEGIN PGP SIGNATURE-----` and end with `-----END PGP SIGNATURE-----`, unless gpg is told to produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`. +Signatures sometimes appear as a part of the normal payload +(e.g. a signed tag has the signature block appended after the payload +that the signature applies to), and sometimes appear in the value of +an object header (e.g. a merge commit that merged a signed tag would +have the entire tag contents on its "mergetag" header). In the case +of the latter, the usual multi-line formatting rule for object +headers applies. I.e. the second and subsequent lines are prefixed +with a SP to signal that the line is continued from the previous +line. + +This is even true for an originally empty line. In the following +examples, the end of line that ends with a whitespace letter is +highlighted with a `$` sign; if you are trying to recreate these +example by hand, do not cut and paste them---they are there +primarily to highlight extra whitespace at the end of some lines. + The signed payload and the way the signature is embedded depends on the type of the object resp. transaction. @@ -78,7 +94,7 @@ author A U Thor <author@example.com> 1465981137 +0000 committer C O Mitter <committer@example.com> 1465981137 +0000 gpgsig -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 - + $ iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/ HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7 DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA @@ -128,13 +144,13 @@ mergetag object 04b871796dc0420f8e7561a895b52484b701d51a type commit tag signedtag tagger C O Mitter <committer@example.com> 1465981006 +0000 - + $ signed tag - + $ signed tag message body -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 - + $ iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods |