diff options
Diffstat (limited to 'Documentation')
39 files changed, 574 insertions, 225 deletions
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 2f8b7d597f..56130e4bec 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -1164,7 +1164,7 @@ After you run this command, `format-patch` will output the patches to the `psuh/ directory, alongside the v1 patches. Using a single directory makes it easy to refer to the old v1 patches while proofreading the v2 patches, but you will need to be careful to send out only the v2 patches. We will use a pattern like -"psuh/v2-*.patch" (not "psuh/*.patch", which would match v1 and v2 patches). +`psuh/v2-*.patch` (not `psuh/*.patch`, which would match v1 and v2 patches). Edit your cover letter again. Now is a good time to mention what's different between your last version and now, if it's something significant. You do not diff --git a/Documentation/RelNotes/2.30.9.txt b/Documentation/RelNotes/2.30.9.txt new file mode 100644 index 0000000000..708d626ce6 --- /dev/null +++ b/Documentation/RelNotes/2.30.9.txt @@ -0,0 +1,43 @@ +Git v2.30.9 Release Notes +========================= + +This release addresses the security issues CVE-2023-25652, +CVE-2023-25815, and CVE-2023-29007. + + +Fixes since v2.30.8 +------------------- + + * CVE-2023-25652: + + By feeding specially crafted input to `git apply --reject`, a + path outside the working tree can be overwritten with partially + controlled contents (corresponding to the rejected hunk(s) from + the given patch). + + * CVE-2023-25815: + + When Git is compiled with runtime prefix support and runs without + translated messages, it still used the gettext machinery to + display messages, which subsequently potentially looked for + translated messages in unexpected places. This allowed for + malicious placement of crafted messages. + + * CVE-2023-29007: + + When renaming or deleting a section from a configuration file, + certain malicious configuration values may be misinterpreted as + the beginning of a new configuration section, leading to arbitrary + configuration injection. + +Credit for finding CVE-2023-25652 goes to Ry0taK, and the fix was +developed by Taylor Blau, Junio C Hamano and Johannes Schindelin, +with the help of Linus Torvalds. + +Credit for finding CVE-2023-25815 goes to Maxime Escourbiac and +Yassine BENGANA of Michelin, and the fix was developed by Johannes +Schindelin. + +Credit for finding CVE-2023-29007 goes to André Baptista and Vítor Pinho +of Ethiack, and the fix was developed by Taylor Blau, and Johannes +Schindelin, with help from Jeff King, and Patrick Steinhardt. diff --git a/Documentation/RelNotes/2.31.8.txt b/Documentation/RelNotes/2.31.8.txt new file mode 100644 index 0000000000..0aa3080780 --- /dev/null +++ b/Documentation/RelNotes/2.31.8.txt @@ -0,0 +1,6 @@ +Git v2.31.8 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9 to address the +security issues CVE-2023-25652, CVE-2023-25815, and CVE-2023-29007; +see the release notes for that version for details. diff --git a/Documentation/RelNotes/2.32.7.txt b/Documentation/RelNotes/2.32.7.txt new file mode 100644 index 0000000000..7bb35388b5 --- /dev/null +++ b/Documentation/RelNotes/2.32.7.txt @@ -0,0 +1,7 @@ +Git v2.32.7 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9 and v2.31.8 to +address the security issues CVE-2023-25652, CVE-2023-25815, and +CVE-2023-29007; see the release notes for these versions for +details. diff --git a/Documentation/RelNotes/2.33.8.txt b/Documentation/RelNotes/2.33.8.txt new file mode 100644 index 0000000000..d8cf4c7f3a --- /dev/null +++ b/Documentation/RelNotes/2.33.8.txt @@ -0,0 +1,7 @@ +Git v2.33.8 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9, v2.31.8 and +v2.32.7 to address the security issues CVE-2023-25652, +CVE-2023-25815, and CVE-2023-29007; see the release notes for these +versions for details. diff --git a/Documentation/RelNotes/2.34.8.txt b/Documentation/RelNotes/2.34.8.txt new file mode 100644 index 0000000000..2b5bd7d9a3 --- /dev/null +++ b/Documentation/RelNotes/2.34.8.txt @@ -0,0 +1,7 @@ +Git v2.34.8 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9, v2.31.8, +v2.32.7 and v2.33.8 to address the security issues CVE-2023-25652, +CVE-2023-25815, and CVE-2023-29007; see the release notes for these +versions for details. diff --git a/Documentation/RelNotes/2.35.8.txt b/Documentation/RelNotes/2.35.8.txt new file mode 100644 index 0000000000..3c9c094c2b --- /dev/null +++ b/Documentation/RelNotes/2.35.8.txt @@ -0,0 +1,7 @@ +Git v2.35.8 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9, v2.31.8, +v2.32.7, v2.33.8 and v2.34.8 to address the security issues +CVE-2023-25652, CVE-2023-25815, and CVE-2023-29007; see the release +notes for these versions for details. diff --git a/Documentation/RelNotes/2.36.6.txt b/Documentation/RelNotes/2.36.6.txt new file mode 100644 index 0000000000..e1edebcc43 --- /dev/null +++ b/Documentation/RelNotes/2.36.6.txt @@ -0,0 +1,7 @@ +Git v2.36.6 Release Notes +========================= + +This release merges the fixes that appear in v2.30.9, v2.31.8, +v2.32.7, v2.33.8, v2.34.8 and v2.35.8 to address the security issues +CVE-2023-25652, CVS-2023-25815, and CVE-2023-29007; see the release +notes for these versions for details. diff --git a/Documentation/RelNotes/2.37.7.txt b/Documentation/RelNotes/2.37.7.txt new file mode 100644 index 0000000000..4b8165f4b5 --- /dev/null +++ b/Documentation/RelNotes/2.37.7.txt @@ -0,0 +1,7 @@ +Git v2.37.7 Release Notes +========================= + +This release merges up the fix that appears in v2.30.9, v2.31.8, +v2.32.7, v2.33.8, v2.34.8, v2.35.8 and v2.36.6 to address the +security issues CVE-2023-25652, CVE-2023-25815, and CVE-2023-29007; +see the release notes for these versions for details. diff --git a/Documentation/RelNotes/2.38.5.txt b/Documentation/RelNotes/2.38.5.txt new file mode 100644 index 0000000000..2d1f3b1249 --- /dev/null +++ b/Documentation/RelNotes/2.38.5.txt @@ -0,0 +1,8 @@ +Git v2.38.5 Release Notes +========================= + +This release merges up the fix that appears in v2.30.9, v2.31.8, +v2.32.7, v2.33.8, v2.34.8, v2.35.8, v2.36.6 and v2.37.7 to address +the security issues CVE-2023-25652, CVE-2023-25815, and +CVE-2023-29007; see the release notes for these versions for +details. diff --git a/Documentation/RelNotes/2.39.3.txt b/Documentation/RelNotes/2.39.3.txt index dddff53627..66351b65c2 100644 --- a/Documentation/RelNotes/2.39.3.txt +++ b/Documentation/RelNotes/2.39.3.txt @@ -1,9 +1,15 @@ Git v2.39.3 Release Notes ========================= -This release is primarily to merge fixes accumulated on the 'master' -front to prepare for 2.40 release that are still relevant to 2.39.x -maintenance track. +This release merges up the fix that appears in v2.30.9, v2.31.8, +v2.32.7, v2.33.8, v2.34.8, v2.35.8, v2.36.6, v2.37.7 and v2.38.5 to +address the security issues CVE-2023-25652, CVE-2023-25815, and +CVE-2023-29007; see the release notes for these versions for +details. + +This release also merges fixes that have accumulated on the 'master' +front to prepare for the 2.40 release that are still relevant to +2.39.x maintenance track. Fixes since v2.39.2 ------------------- diff --git a/Documentation/RelNotes/2.40.1.txt b/Documentation/RelNotes/2.40.1.txt new file mode 100644 index 0000000000..e72f6b1b25 --- /dev/null +++ b/Documentation/RelNotes/2.40.1.txt @@ -0,0 +1,8 @@ +Git v2.40.1 Release Notes +========================= + +This release merges up the fix that appears in v2.30.9, v2.31.8, +v2.32.7, v2.33.8, v2.34.8, v2.35.8, v2.36.6, v2.37.7, v2.38.5 +and v2.39.3 to address the security issues CVE-2023-25652, +CVE-2023-25815, and CVE-2023-29007; see the release notes for these +versions for details. diff --git a/Documentation/RelNotes/2.41.0.txt b/Documentation/RelNotes/2.41.0.txt index 0fc82a83fc..fa2834bd72 100644 --- a/Documentation/RelNotes/2.41.0.txt +++ b/Documentation/RelNotes/2.41.0.txt @@ -50,6 +50,47 @@ UI, Workflows & Features choice of the hash algorithm from the source repository to the newly created repository. + * "git mergetool" and "git difftool" learns a new configuration + guiDefault to optionally favor configured guitool over non-gui-tool + automatically when $DISPLAY is set. + + * "git branch -d origin/master" would say "no such branch", but it is + likely a missed "-r" if refs/remotes/origin/master exists. The + command has been taught to give such a hint in its error message. + + * Clean-up of the code path that deals with merge strategy option + handling in "git rebase". + + * "git clone --local" stops copying from an original repository that + has symbolic links inside its $GIT_DIR; an error message when that + happens has been updated. + + * "git branch --format=..." and "git format-patch --format=..." + learns "--omit-empty" to hide refs that whose formatting result + becomes an empty string from the output. + + * The sendemail-validate validate hook learned to pass the total + number of input files and where in the sequence each invocation is + via environment variables. + + * When "gc" needs to retain unreachable objects, packing them into + cruft packs (instead of exploding them into loose object files) has + been offered as a more efficient option for some time. Now the use + of cruft packs has been made the default and no longer considered + an experimental feature. + + * The output given by "git blame" that attributes a line to contents + taken from the file specified by the "--contents" option shows it + differently from a line attributed to the working tree file. + + * "git send-email" learned to give the e-mail headers to the validate + hook by passing an extra argument from the command line. + + * The credential subsystem learns to help OAuth framework. + + * The titles of manual pages used to be chomped at an unreasonably + short limit, which has been removed. + Performance, Internal Implementation, Development Support etc. @@ -88,6 +129,37 @@ Performance, Internal Implementation, Development Support etc. * "git sparse-checkout" command learns a debugging aid for the sparse rule definitions. + * "git write-tree" learns to work better with sparse-index. + + * The on-disk reverse index that allows mapping from the pack offset + to the object name for the object stored at the offset has been + enabled by default. + + * "git fsck" learned to validate the on-disk pack reverse index files. + + * strtok() and strtok_r() are banned in this codebase. + + * The detect-compilers script to help auto-tweaking the build system + had trouble working with compilers whose version number has extra + suffixes. The script has been taught that certain suffixes (like + "-win32" in "gcc 10-win32") can be safely stripped as they share + the same features and bugs with the version without the suffix. + + * ctype tests have been taught to test EOF, too. + + * The implementation of credential helpers used fgets() over fixed + size buffers to read protocol messages, causing the remainder of + the folded long line to trigger unexpected behaviour, which has + been corrected. + + * The implementation of the default "negotiator", used to find common + ancestor over the network for object tranfer, used to be recursive; + it was updated to be iterative to conserve stackspace usage. + + * Our custom callout formatter is no longer used in the documentation + formatting toolchain, as the upstream default ones give better + output these days. + Fixes since v2.40 ----------------- @@ -193,6 +265,66 @@ Fixes since v2.40 /usr/bin/perl, which have been corrected. (merge c1917156a0 jk/use-perl-path-consistently later to maint). + * Documentation mark-up fix. + (merge 78b6369e67 la/mfc-markup-fix later to maint). + + * Doc toolchain update to remove old workaround for AsciiDoc. + (merge 8806120de6 fc/remove-header-workarounds-for-asciidoc later to maint). + + * The userdiff regexp patterns for various filetypes that are built + into the system have been updated to avoid triggering regexp errors + from UTF-8 aware regex engines. + (merge be39144954 rs/userdiff-multibyte-regex later to maint). + + * The approxidate() API has been simplified by losing an extra + function that did the same thing as another one. + (merge 8a7f0b666f rs/remove-approxidate-relative later to maint). + + * Code clean-up to replace a hardcoded constant with a CPP macro. + (merge c870de6502 rs/get-tar-commit-id-use-defined-const later to maint). + + * Doc build simplification. + (merge 9a09ed3229 fc/doc-stop-using-manversion later to maint). + + * "git archive" run from a subdirectory mishandled attributes and + paths outside the current directory. + (merge 92b1dd1b9e rs/archive-from-subdirectory-fixes later to maint). + + * The code to parse capability list for v0 on-wire protocol fell into + an infinite loop when a capability appears multiple times, which + has been corrected. + + * Geometric repacking ("git repack --geometric=<n>") in a repository + that borrows from an alternate object database had various corner + case bugs, which have been corrected. + (merge d85cd18777 ps/fix-geom-repack-with-alternates later to maint). + + * The "%GT" placeholder for the "--format" option of "git log" and + friends caused BUG() to trigger on a commit signed with an unknown + key, which has been corrected. + (merge 7891e46585 jk/gpg-trust-level-fix later to maint). + + * The completion script used to use bare "read" without the "-r" + option to read the contents of various state files, which risked + getting confused with backslashes in them. This has been + corrected. + (merge 197152098a ek/completion-use-read-r-to-read-literally later to maint). + + * A small API fix to the ort merge strategy backend. + (merge 000c4ceca7 en/ort-finalize-after-0-merges-fix later to maint). + + * The commit object parser has been taught to be a bit more lenient + to parse timestamps on the author/committer line with a malformed + author/committer ident. + (merge 90ef0f14eb jk/parse-commit-with-malformed-ident later to maint). + + * Retitle a test script with an overly narrow name. + (merge 8bb19c14fb ob/t3501-retitle later to maint). + + * Doc update to clarify how text and eol attributes interact to + specify the end-of-line conversion. + (merge 6696077ace ah/doc-attributes-text later to maint). + * Other code cleanup, docfix, build fix, etc. (merge f7111175df as/doc-markup-fix later to maint). (merge 90ff7c9898 fc/test-aggregation-clean-up later to maint). @@ -208,3 +340,9 @@ Fixes since v2.40 (merge cc48ddd937 jk/chainlint-fixes later to maint). (merge 4833b08426 ow/ref-format-remove-unused-member later to maint). (merge d0ea2ca1cf dw/doc-submittingpatches-grammofix later to maint). + (merge fd72637423 ar/t2024-checkout-output-fix later to maint). + (merge d45cbe3fe0 ob/sequencer-i18n-fix later to maint). + (merge b734fe49fd ob/messages-capitalize-exception later to maint). + (merge ad353d7e77 ma/gittutorial-fixes later to maint). + (merge a5855fd8d4 ar/test-cleanup-unused-file-creation-part2 later to maint). + (merge 0c5308af30 sd/doc-gitignore-and-rm-cached later to maint). diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 95599bd6e5..552dcc60f2 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -64,11 +64,9 @@ include::line-range-format.txt[] manual page. --contents <file>:: - Pretend the file being annotated has a commit with the - contents from the named file and a parent of <rev>, - defaulting to HEAD when no <rev> is specified. You may - specify '-' to make the command read from the standard - input for the file contents. + Annotate using the contents from the named file, starting from <rev> + if it is specified, and HEAD otherwise. You may specify '-' to make + the command read from the standard input for the file contents. --date <format>:: Specifies the format used to output dates. If --date is not diff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt index a3f8211210..447c40d85a 100644 --- a/Documentation/config/difftool.txt +++ b/Documentation/config/difftool.txt @@ -34,3 +34,10 @@ See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details. difftool.prompt:: Prompt before each invocation of the diff tool. + +difftool.guiDefault:: + Set `true` to use the `diff.guitool` by default (equivalent to specifying + the `--gui` argument), or `auto` to select `diff.guitool` or `diff.tool` + depending on the presence of a `DISPLAY` environment variable value. The + default is `false`, where the `--gui` argument must be provided + explicitly for the `diff.guitool` to be used. diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt index e52bc6b858..17b4d39f89 100644 --- a/Documentation/config/feature.txt +++ b/Documentation/config/feature.txt @@ -14,9 +14,6 @@ feature.experimental:: + * `fetch.negotiationAlgorithm=skipping` may improve fetch negotiation times by skipping more commits at a time, reducing the number of round trips. -+ -* `gc.cruftPacks=true` reduces disk space used by unreachable objects during -garbage collection, preventing loose object explosions. 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 38fea076a2..7f95c866e1 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -43,11 +43,11 @@ gc.autoDetach:: if the system supports it. Default is true. gc.bigPackThreshold:: - If non-zero, all packs larger than this limit are kept when - `git gc` is run. This is very similar to `--keep-largest-pack` - except that all packs that meet the threshold are kept, not - just the largest pack. Defaults to zero. Common unit suffixes of - 'k', 'm', or 'g' are supported. + If non-zero, all non-cruft packs larger than this limit are kept + when `git gc` is run. This is very similar to + `--keep-largest-pack` except that all non-cruft packs that meet + the threshold are kept, not just the largest pack. Defaults to + zero. Common unit suffixes of 'k', 'm', or 'g' are supported. + Note that if the number of kept packs is more than gc.autoPackLimit, this configuration variable is ignored, all packs except the base pack @@ -84,7 +84,7 @@ gc.packRefs:: gc.cruftPacks:: Store unreachable objects in a cruft pack (see linkgit:git-repack[1]) instead of as loose objects. The default - is `false`. + is `true`. gc.pruneExpire:: When 'git gc' is run, it will call 'prune --expire 2.weeks.ago' diff --git a/Documentation/config/mergetool.txt b/Documentation/config/mergetool.txt index e779a122d8..56a7eeeffb 100644 --- a/Documentation/config/mergetool.txt +++ b/Documentation/config/mergetool.txt @@ -85,3 +85,10 @@ mergetool.writeToTemp:: mergetool.prompt:: Prompt before each invocation of the merge resolution program. + +mergetool.guiDefault:: + Set `true` to use the `merge.guitool` by default (equivalent to + specifying the `--gui` argument), or `auto` to select `merge.guitool` + or `merge.tool` depending on the presence of a `DISPLAY` environment + variable value. The default is `false`, where the `--gui` argument + must be provided explicitly for the `merge.guitool` to be used. diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt index 53093d9996..d4c7c9d4e4 100644 --- a/Documentation/config/pack.txt +++ b/Documentation/config/pack.txt @@ -171,9 +171,15 @@ pack.writeBitmapLookupTable:: beneficial in repositories that have relatively large bitmap indexes. Defaults to false. +pack.readReverseIndex:: + When true, git will read any .rev file(s) that may be available + (see: linkgit:gitformat-pack[5]). When false, the reverse index + will be generated from scratch and stored in memory. Defaults to + true. + pack.writeReverseIndex:: When true, git will write a corresponding .rev file (see: linkgit:gitformat-pack[5]) for each new packfile that it writes in all places except for linkgit:git-fast-import[1] and in the bulk checkin mechanism. - Defaults to false. + Defaults to true. diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt index 51da7088a8..92a9ebe98c 100644 --- a/Documentation/config/sendemail.txt +++ b/Documentation/config/sendemail.txt @@ -61,6 +61,7 @@ sendemail.ccCmd:: sendemail.chainReplyTo:: sendemail.envelopeSender:: sendemail.from:: +sendemail.headerCmd:: sendemail.signedoffbycc:: sendemail.smtpPass:: sendemail.suppresscc:: diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index d382ac69f7..d207da9101 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -156,6 +156,10 @@ in another worktree linked to the same repository. --ignore-case:: Sorting and filtering branches are case insensitive. +--omit-empty:: + Do not print a newline after formatted refs where the format expands + to the empty string. + --column[=<options>]:: --no-column:: Display branch listing in columns. See configuration variable diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 6bb32ab460..4af0904f47 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -483,14 +483,11 @@ $ git checkout -b foo # or "git switch -c foo" <1> $ git branch foo <2> $ git tag foo <3> ------------ - <1> creates a new branch `foo`, which refers to commit `f`, and then updates `HEAD` to refer to branch `foo`. In other words, we'll no longer be in detached `HEAD` state after this command. - <2> similarly creates a new branch `foo`, which refers to commit `f`, but leaves `HEAD` detached. - <3> creates a new tag `foo`, which refers to commit `f`, leaving `HEAD` detached. @@ -519,84 +516,89 @@ to checkout these paths out of the index. EXAMPLES -------- -. The following sequence checks out the `master` branch, reverts - the `Makefile` to two revisions back, deletes `hello.c` by - mistake, and gets it back from the index. -+ +=== 1. Paths + +The following sequence checks out the `master` branch, reverts +the `Makefile` to two revisions back, deletes `hello.c` by +mistake, and gets it back from the index. + ------------ $ git checkout master <1> $ git checkout master~2 Makefile <2> $ rm -f hello.c $ git checkout hello.c <3> ------------ -+ <1> switch branch <2> take a file out of another commit <3> restore `hello.c` from the index -+ + If you want to check out _all_ C source files out of the index, you can say -+ + ------------ $ git checkout -- '*.c' ------------ -+ + Note the quotes around `*.c`. The file `hello.c` will also be checked out, even though it is no longer in the working tree, because the file globbing is used to match entries in the index (not in the working tree by the shell). -+ + If you have an unfortunate branch that is named `hello.c`, this step would be confused as an instruction to switch to that branch. You should instead write: -+ + ------------ $ git checkout -- hello.c ------------ -. After working in the wrong branch, switching to the correct - branch would be done using: -+ +=== 2. Merge + +After working in the wrong branch, switching to the correct +branch would be done using: + ------------ $ git checkout mytopic ------------ -+ + However, your "wrong" branch and correct `mytopic` branch may differ in files that you have modified locally, in which case the above checkout would fail like this: -+ + ------------ $ git checkout mytopic error: You have local changes to 'frotz'; not switching branches. ------------ -+ + You can give the `-m` flag to the command, which would try a three-way merge: -+ + ------------ $ git checkout -m mytopic Auto-merging frotz ------------ -+ + After this three-way merge, the local modifications are _not_ registered in your index file, so `git diff` would show you what changes you made since the tip of the new branch. -. When a merge conflict happens during switching branches with - the `-m` option, you would see something like this: -+ +=== 3. Merge conflict + +When a merge conflict happens during switching branches with +the `-m` option, you would see something like this: + ------------ $ git checkout -m mytopic Auto-merging frotz ERROR: Merge conflict in frotz fatal: merge program failed ------------ -+ + At this point, `git diff` shows the changes cleanly merged as in the previous example, as well as the changes in the conflicted files. Edit and resolve the conflict and mark it resolved with `git add` as usual: -+ + ------------ $ edit frotz $ git add frotz diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index d6434d262d..c37c4a37f7 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -58,6 +58,11 @@ never use the local optimizations). Specifying `--no-local` will override the default when `/path/to/repo` is given, using the regular Git transport instead. + +If the repository's `$GIT_DIR/objects` has symbolic links or is a +symbolic link, the clone will fail. This is a security measure to +prevent the unintentional copying of files by dereferencing the symbolic +links. ++ *NOTE*: this operation can race with concurrent modification to the source repository, similar to running `cp -r src dst` while modifying `src`. diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 3394c03611..0e6d9e85ec 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -156,6 +156,12 @@ Git understands the following attributes: When reading credentials from helpers, `git credential fill` ignores expired passwords. Represented as Unix time UTC, seconds since 1970. +`oauth_refresh_token`:: + + An OAuth refresh token may accompany a password that is an OAuth access + token. Helpers must treat this attribute as confidential like the password + attribute. Git itself has no special behaviour for this attribute. + `url`:: When this special attribute is read by `git credential`, the diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 9d14c3c9f0..ac0ac6fa02 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -97,10 +97,12 @@ instead. `--no-symlinks` is the default on Windows. --[no-]gui:: When 'git-difftool' is invoked with the `-g` or `--gui` option the default diff tool will be read from the configured - `diff.guitool` variable instead of `diff.tool`. The `--no-gui` - option can be used to override this setting. If `diff.guitool` - is not set, we will fallback in the order of `merge.guitool`, - `diff.tool`, `merge.tool` until a tool is found. + `diff.guitool` variable instead of `diff.tool`. This may be + selected automatically using the configuration variable + `difftool.guiDefault`. The `--no-gui` option can be used to + override these settings. If `diff.guitool` is not set, we will + fallback in the order of `merge.guitool`, `diff.tool`, + `merge.tool` until a tool is found. --[no-]trust-exit-code:: 'git-difftool' invokes a diff tool individually on each file. diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 0713e49b49..1e215d4e73 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -98,6 +98,10 @@ OPTIONS --ignore-case:: Sorting and filtering refs are case insensitive. +--omit-empty:: + Do not print a newline after formatted refs where the format expands + to the empty string. + FIELD NAMES ----------- diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 508f3ae2c0..b1c13fb39a 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -173,8 +173,7 @@ series, where the head is chosen from the cover letter, the threading makes every mail a reply to the previous one. + The default is `--no-thread`, unless the `format.thread` configuration -is set. If `--thread` is specified without a style, it defaults to the -style specified by `format.thread` if any, or else `shallow`. +is set. `--thread` without an argument is equivalent to `--thread=shallow`. + Beware that the default for 'git send-email' is to thread emails itself. If you want `git format-patch` to take care of threading, you diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index a65c9aa62d..90806fd26a 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -54,9 +54,10 @@ other housekeeping tasks (e.g. rerere, working trees, reflog...) will be performed as well. ---cruft:: +--[no-]cruft:: When expiring unreachable objects, pack them separately into a - cruft pack instead of storing them as loose objects. + cruft pack instead of storing them as loose objects. `--cruft` + is on by default. --prune=<date>:: Prune loose objects older than date (default is 2 weeks ago, @@ -77,9 +78,10 @@ be performed as well. instance running on this repository. --keep-largest-pack:: - All packs except the largest pack and those marked with a - `.keep` files are consolidated into a single pack. When this - option is used, `gc.bigPackThreshold` is ignored. + All packs except the largest non-cruft pack, any packs marked + with a `.keep` file, and any cruft pack(s) are consolidated into + a single pack. When this option is used, `gc.bigPackThreshold` + is ignored. AGGRESSIVE ---------- diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index 22ff3a603e..4b97f812be 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -280,7 +280,7 @@ $ cat msg.txt subject message -$ cat msg.txt | git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' +$ git interpret-trailers --trailer 'sign: Alice <alice@example.com>' --trailer 'sign: Bob <bob@example.com>' <msg.txt subject message @@ -322,17 +322,30 @@ $ git interpret-trailers --trailer 'Cc: Alice <alice@example.com>' --trailer 'Re 'Signed-off-by: ' already, and show how it works: + ------------ +$ cat msg1.txt +subject + +message $ git config trailer.sign.key "Signed-off-by: " $ git config trailer.sign.ifmissing add $ git config trailer.sign.ifexists doNothing -$ git config trailer.sign.command 'echo "$(git config user.name) <$(git config user.email)>"' -$ git interpret-trailers <<EOF -> EOF +$ git config trailer.sign.cmd 'echo "$(git config user.name) <$(git config user.email)>"' +$ git interpret-trailers --trailer sign <msg1.txt +subject + +message Signed-off-by: Bob <bob@example.com> -$ git interpret-trailers <<EOF -> Signed-off-by: Alice <alice@example.com> -> EOF +$ cat msg2.txt +subject + +message + +Signed-off-by: Alice <alice@example.com> +$ git interpret-trailers --trailer sign <msg2.txt +subject + +message Signed-off-by: Alice <alice@example.com> ------------ @@ -357,15 +370,14 @@ Fix #42 $ cat ~/bin/glog-find-author #!/bin/sh test -n "$1" && git log --author="$1" --pretty="%an <%ae>" -1 || true +$ cat msg.txt +subject + +message $ 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" <<EOF -> subject -> -> message -> -> EOF +$ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" <msg.txt subject message @@ -382,15 +394,14 @@ Helped-by: Christian Couder <christian.couder@gmail.com> $ cat ~/bin/glog-grep #!/bin/sh test -n "$1" && git log --grep "$1" --pretty=reference -1 || true +$ cat msg.txt +subject + +message $ 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." <<EOF -> subject -> -> message -> -> EOF +$ git interpret-trailers --trailer="ref:Add copyright notices." <msg.txt subject message @@ -402,17 +413,20 @@ Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07) commit that is related, and show how it works: + ------------ +$ cat msg.txt +subject + +message + +see: HEAD~2 +$ cat ~/bin/glog-ref +#!/bin/sh +git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14 $ git config trailer.see.key "See-also: " $ git config trailer.see.ifExists "replace" $ git config trailer.see.ifMissing "doNothing" -$ git config trailer.see.command "git log -1 --oneline --format=\"%h (%s)\" --abbrev-commit --abbrev=14 \$ARG" -$ git interpret-trailers <<EOF -> subject -> -> message -> -> see: HEAD~2 -> EOF +$ git config trailer.see.cmd "glog-ref" +$ git interpret-trailers --trailer=see <msg.txt subject message @@ -427,22 +441,21 @@ See-also: fe3187489d69c4 (subject of related commit) to add a 'git-version' trailer: + ------------ -$ sed -e 's/ Z$/ /' >commit_template.txt <<EOF -> ***subject*** -> -> ***message*** -> -> Fixes: Z -> Cc: Z -> Reviewed-by: Z -> Signed-off-by: Z -> EOF +$ cat temp.txt +***subject*** + +***message*** + +Fixes: Z +Cc: Z +Reviewed-by: Z +Signed-off-by: Z +$ sed -e 's/ Z$/ /' temp.txt > commit_template.txt $ git config commit.template commit_template.txt -$ cat >.git/hooks/commit-msg <<EOF -> #!/bin/sh -> git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new" -> mv "\$1.new" "\$1" -> EOF +$ cat .git/hooks/commit-msg +#!/bin/sh +git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" > "\$1.new" +mv "\$1.new" "\$1" $ chmod +x .git/hooks/commit-msg ------------ diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index c44e205629..07535f6576 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -85,12 +85,13 @@ success of the resolution after the custom tool has exited. the default merge tool will be read from the configured `merge.guitool` variable instead of `merge.tool`. If `merge.guitool` is not set, we will fallback to the tool - configured under `merge.tool`. + configured under `merge.tool`. This may be autoselected using + the configuration variable `mergetool.guiDefault`. --no-gui:: - This overrides a previous `-g` or `--gui` setting and reads the - default merge tool will be read from the configured `merge.tool` - variable. + This overrides a previous `-g` or `--gui` setting or + `mergetool.guiDefault` configuration and reads the default merge + tool from the configured `merge.tool` variable. -O<orderfile>:: Process files in the order specified in the diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index b0f438ec99..492a82323d 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -320,6 +320,17 @@ Automating Output of this command must be single email address per line. Default is the value of `sendemail.ccCmd` configuration value. +--header-cmd=<command>:: + Specify a command that is executed once per outgoing message + and output RFC 2822 style header lines to be inserted into + them. When the `sendemail.headerCmd` configuration variable is + set, its value is always used. When --header-cmd is provided + at the command line, its value takes precedence over the + `sendemail.headerCmd` configuration variable. + +--no-header-cmd:: + Disable any header command in use. + --[no-]chain-reply-to:: If this is set, each email will be sent as a reply to the previous email sent. If disabled with "--no-chain-reply-to", all emails after @@ -484,14 +495,10 @@ edit ~/.gitconfig to specify your account settings: smtpServerPort = 587 ---- -If you have multi-factor authentication set up on your Gmail account, you will -need to generate an app-specific password for use with 'git send-email'. Visit +If you have multi-factor authentication set up on your Gmail account, you can +generate an app-specific password for use with 'git send-email'. Visit https://security.google.com/settings/security/apppasswords to create it. -If you do not have multi-factor authentication set up on your Gmail account, -you will need to allow less secure app access. Visit -https://myaccount.google.com/lesssecureapps to enable it. - Once your commits are ready to be sent to the mailing list, run the following commands: diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index fdc72b5875..7f61c1edb3 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -131,6 +131,10 @@ options for details. --ignore-case:: Sorting and filtering tags are case insensitive. +--omit-empty:: + Do not print a newline after formatted refs where the format expands + to the empty string. + --column[=<options>]:: --no-column:: Display tag listing in columns. See configuration variable diff --git a/Documentation/git.txt b/Documentation/git.txt index 74973d3cc4..54b043899f 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -546,9 +546,9 @@ double-quotes and respecting backslash escapes. E.g., the value `GIT_DEFAULT_HASH`:: If this variable is set, the default hash algorithm for new - repositories will be set to this value. This value is currently - ignored when cloning; the setting of the remote repository - is used instead. The default is "sha1". THIS VARIABLE IS + repositories will be set to this value. This value is + ignored when cloning and the setting of the remote repository + is always used. The default is "sha1". THIS VARIABLE IS EXPERIMENTAL! See `--object-format` in linkgit:git-init[1]. Git Commits diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 39bfbca1ff..02a3ec83e4 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -120,20 +120,19 @@ repository upon 'git add' and 'git commit'. `text` ^^^^^^ -This attribute enables and controls end-of-line normalization. When a -text file is normalized, its line endings are converted to LF in the -repository. To control what line ending style is used in the working -directory, use the `eol` attribute for a single file and the -`core.eol` configuration variable for all text files. -Note that setting `core.autocrlf` to `true` or `input` overrides -`core.eol` (see the definitions of those options in -linkgit:git-config[1]). +This attribute marks the path as a text file, which enables end-of-line +conversion: When a matching file is added to the index, the file's line +endings are normalized to LF in the index. Conversely, when the file is +copied from the index to the working directory, its line endings may be +converted from LF to CRLF depending on the `eol` attribute, the Git +config, and the platform (see explanation of `eol` below). Set:: Setting the `text` attribute on a path enables end-of-line - normalization and marks the path as a text file. End-of-line - conversion takes place without guessing the content type. + conversion on checkin and checkout as described above. Line endings + are normalized to LF in the index every time the file is checked in, + even if the file was previously added to Git with CRLF line endings. Unset:: @@ -142,10 +141,11 @@ Unset:: Set to string value "auto":: - When `text` is set to "auto", the path is marked for automatic - end-of-line conversion. If Git decides that the content is - text, its line endings are converted to LF on checkin. - When the file has been committed with CRLF, no conversion is done. + When `text` is set to "auto", Git decides by itself whether the file + is text or binary. If it is text and the file was not already in + Git with CRLF endings, line endings are converted on checkin and + checkout as described above. Otherwise, no conversion is done on + checkin or checkout. Unspecified:: @@ -159,26 +159,29 @@ unspecified. `eol` ^^^^^ -This attribute sets a specific line-ending style to be used in the -working directory. This attribute has effect only if the `text` -attribute is set or unspecified, or if it is set to `auto`, the file is -detected as text, and it is stored with LF endings in the index. Note -that setting this attribute on paths which are in the index with CRLF -line endings may make the paths to be considered dirty unless -`text=auto` is set. Adding the path to the index again will normalize -the line endings in the index. +This attribute marks a path to use a specific line-ending style in the +working tree when it is checked out. It has effect only if `text` or +`text=auto` is set (see above), but specifying `eol` automatically sets +`text` if `text` was left unspecified. Set to string value "crlf":: - This setting forces Git to normalize line endings for this - file on checkin and convert them to CRLF when the file is - checked out. + This setting converts the file's line endings in the working + directory to CRLF when the file is checked out. Set to string value "lf":: - This setting forces Git to normalize line endings to LF on - checkin and prevents conversion to CRLF when the file is - checked out. + This setting uses the same line endings in the working directory as + in the index when the file is checked out. + +Unspecified:: + + If the `eol` attribute is unspecified for a file, its line endings + in the working directory are determined by the `core.autocrlf` or + `core.eol` configuration variable (see the definitions of those + options in linkgit:git-config[1]). If `text` is set but neither of + those variables is, the default is `eol=crlf` on Windows and + `eol=lf` on all other platforms. Backwards compatibility with `crlf` attribute ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/gitformat-pack.txt b/Documentation/gitformat-pack.txt index e06af02f21..0c1be2dbe8 100644 --- a/Documentation/gitformat-pack.txt +++ b/Documentation/gitformat-pack.txt @@ -611,8 +611,8 @@ result of repeatedly resetting the objects' mtimes to the present time. If you are GC-ing repositories in a mixed version environment, consider omitting the `--cruft` option when using linkgit:git-repack[1] and linkgit:git-gc[1], and -leaving the `gc.cruftPacks` configuration unset until all writers understand -cruft packs. +setting the `gc.cruftPacks` configuration to "false" until all writers +understand cruft packs. === Alternatives diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 62908602e7..86f804720a 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -595,10 +595,51 @@ processed by rebase. sendemail-validate ~~~~~~~~~~~~~~~~~~ -This hook is invoked by linkgit:git-send-email[1]. It takes a single parameter, -the name of the file that holds the e-mail to be sent. Exiting with a -non-zero status causes `git send-email` to abort before sending any -e-mails. +This hook is invoked by linkgit:git-send-email[1]. + +It takes these command line arguments. They are, +1. the name of the file which holds the contents of the email to be sent. +2. The name of the file which holds the SMTP headers of the email. + +The SMTP headers are passed in the exact same way as they are passed to the +user's Mail Transport Agent (MTA). In effect, the email given to the user's +MTA, is the contents of $2 followed by the contents of $1. + +An example of a few common headers is shown below. Take notice of the +capitalization and multi-line tab structure. + + From: Example <from@example.com> + To: to@example.com + Cc: cc@example.com, + A <author@example.com>, + One <one@example.com>, + two@example.com + Subject: PATCH-STRING + +Exiting with a non-zero status causes `git send-email` to abort +before sending any e-mails. + +The following environment variables are set when executing the hook. + +`GIT_SENDEMAIL_FILE_COUNTER`:: + A 1-based counter incremented by one for every file holding an e-mail + to be sent (excluding any FIFOs). This counter does not follow the + patch series counter scheme. It will always start at 1 and will end at + GIT_SENDEMAIL_FILE_TOTAL. + +`GIT_SENDEMAIL_FILE_TOTAL`:: + The total number of files that will be sent (excluding any FIFOs). This + counter does not follow the patch series counter scheme. It will always + be equal to the number of files being sent, whether there is a cover + letter or not. + +These variables may for instance be used to validate patch series. + +The sample `sendemail-validate` hook that comes with Git checks that all sent +patches (excluding the cover letter) can be applied on top of the upstream +repository default branch without conflicts. Some placeholders are left for +additional validation steps to be performed after all patches of a given series +have been applied. fsmonitor-watchman ~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index f2738b10db..4c17f2356c 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -146,7 +146,9 @@ The purpose of gitignore files is to ensure that certain files not tracked by Git remain untracked. To stop tracking a file that is currently tracked, use -'git rm --cached'. +'git rm --cached' to remove the file from the index. The filename +can then be added to the `.gitignore` file to stop the file from +being reintroduced in later commits. Git does not follow symbolic links when accessing a `.gitignore` file in the working tree. This keeps behavior consistent when the file is diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index 0e0b863105..c7cadd8aaf 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -49,7 +49,7 @@ $ git config --global user.email you@yourdomain.example.com Importing a new project ----------------------- -Assume you have a tarball project.tar.gz with your initial work. You +Assume you have a tarball `project.tar.gz` with your initial work. You can place it under Git revision control as follows. ------------------------------------------------ @@ -65,10 +65,10 @@ Initialized empty Git repository in .git/ ------------------------------------------------ You've now initialized the working directory--you may notice a new -directory created, named ".git". +directory created, named `.git`. Next, tell Git to take a snapshot of the contents of all files under the -current directory (note the '.'), with 'git add': +current directory (note the `.`), with `git add`: ------------------------------------------------ $ git add . @@ -76,7 +76,7 @@ $ git add . This snapshot is now stored in a temporary staging area which Git calls the "index". You can permanently store the contents of the index in the -repository with 'git commit': +repository with `git commit`: ------------------------------------------------ $ git commit @@ -95,21 +95,20 @@ $ git add file1 file2 file3 ------------------------------------------------ You are now ready to commit. You can see what is about to be committed -using 'git diff' with the --cached option: +using `git diff` with the `--cached` option: ------------------------------------------------ $ git diff --cached ------------------------------------------------ -(Without --cached, 'git diff' will show you any changes that +(Without `--cached`, `git diff` will show you any changes that you've made but not yet added to the index.) You can also get a brief -summary of the situation with 'git status': +summary of the situation with `git status`: ------------------------------------------------ $ git status On branch master Changes to be committed: -Your branch is up to date with 'origin/master'. (use "git restore --staged <file>..." to unstage) modified: file1 @@ -128,7 +127,7 @@ $ git commit This will again prompt you for a message describing the change, and then record a new version of the project. -Alternatively, instead of running 'git add' beforehand, you can use +Alternatively, instead of running `git add` beforehand, you can use ------------------------------------------------ $ git commit -a @@ -151,7 +150,7 @@ Git tracks content not files Many revision control systems provide an `add` command that tells the system to start tracking changes to a new file. Git's `add` command -does something simpler and more powerful: 'git add' is used both for new +does something simpler and more powerful: `git add` is used both for new and newly modified files, and in both cases it takes a snapshot of the given files and stages that content in the index, ready for inclusion in the next commit. @@ -182,7 +181,7 @@ Managing branches ----------------- A single Git repository can maintain multiple branches of -development. To create a new branch named "experimental", use +development. To create a new branch named `experimental`, use ------------------------------------------------ $ git branch experimental @@ -201,8 +200,8 @@ you'll get a list of all existing branches: * master ------------------------------------------------ -The "experimental" branch is the one you just created, and the -"master" branch is a default branch that was created for you +The `experimental` branch is the one you just created, and the +`master` branch is a default branch that was created for you automatically. The asterisk marks the branch you are currently on; type @@ -210,8 +209,8 @@ type $ git switch experimental ------------------------------------------------ -to switch to the experimental branch. Now edit a file, commit the -change, and switch back to the master branch: +to switch to the `experimental` branch. Now edit a file, commit the +change, and switch back to the `master` branch: ------------------------------------------------ (edit file) @@ -220,9 +219,9 @@ $ git switch master ------------------------------------------------ Check that the change you made is no longer visible, since it was -made on the experimental branch and you're back on the master branch. +made on the `experimental` branch and you're back on the `master` branch. -You can make a different change on the master branch: +You can make a different change on the `master` branch: ------------------------------------------------ (edit file) @@ -230,7 +229,7 @@ $ git commit -a ------------------------------------------------ at this point the two branches have diverged, with different changes -made in each. To merge the changes made in experimental into master, run +made in each. To merge the changes made in `experimental` into `master`, run ------------------------------------------------ $ git merge experimental @@ -258,16 +257,16 @@ $ gitk will show a nice graphical representation of the resulting history. -At this point you could delete the experimental branch with +At this point you could delete the `experimental` branch with ------------------------------------------------ $ git branch -d experimental ------------------------------------------------ -This command ensures that the changes in the experimental branch are +This command ensures that the changes in the `experimental` branch are already in the current branch. -If you develop on a branch crazy-idea, then regret it, you can always +If you develop on a branch `crazy-idea`, then regret it, you can always delete the branch with ------------------------------------- @@ -281,7 +280,7 @@ Using Git for collaboration --------------------------- Suppose that Alice has started a new project with a Git repository in -/home/alice/project, and that Bob, who has a home directory on the +`/home/alice/project`, and that Bob, who has a home directory on the same machine, wants to contribute. Bob begins with: @@ -290,7 +289,7 @@ Bob begins with: bob$ git clone /home/alice/project myrepo ------------------------------------------------ -This creates a new directory "myrepo" containing a clone of Alice's +This creates a new directory `myrepo` containing a clone of Alice's repository. The clone is on an equal footing with the original project, possessing its own copy of the original project's history. @@ -303,31 +302,31 @@ bob$ git commit -a ------------------------------------------------ When he's ready, he tells Alice to pull changes from the repository -at /home/bob/myrepo. She does this with: +at `/home/bob/myrepo`. She does this with: ------------------------------------------------ alice$ cd /home/alice/project alice$ git pull /home/bob/myrepo master ------------------------------------------------ -This merges the changes from Bob's "master" branch into Alice's +This merges the changes from Bob's `master` branch into Alice's current branch. If Alice has made her own changes in the meantime, then she may need to manually fix any conflicts. -The "pull" command thus performs two operations: it fetches changes +The `pull` command thus performs two operations: it fetches changes from a remote branch, then merges them into the current branch. Note that in general, Alice would want her local changes committed before -initiating this "pull". If Bob's work conflicts with what Alice did since +initiating this `pull`. If Bob's work conflicts with what Alice did since their histories forked, Alice will use her working tree and the index to resolve conflicts, and existing local changes will interfere with the conflict resolution process (Git will still perform the fetch but will refuse to merge -- Alice will have to get rid of her local changes in some way and pull again when this happens). -Alice can peek at what Bob did without merging first, using the "fetch" +Alice can peek at what Bob did without merging first, using the `fetch` command; this allows Alice to inspect what Bob did, using a special -symbol "FETCH_HEAD", in order to determine if he has anything worth +symbol `FETCH_HEAD`, in order to determine if he has anything worth pulling, like this: ------------------------------------------------ @@ -336,10 +335,10 @@ alice$ git log -p HEAD..FETCH_HEAD ------------------------------------------------ This operation is safe even if Alice has uncommitted local changes. -The range notation "HEAD..FETCH_HEAD" means "show everything that is reachable -from the FETCH_HEAD but exclude anything that is reachable from HEAD". -Alice already knows everything that leads to her current state (HEAD), -and reviews what Bob has in his state (FETCH_HEAD) that she has not +The range notation `HEAD..FETCH_HEAD` means "show everything that is reachable +from the `FETCH_HEAD` but exclude anything that is reachable from `HEAD`". +Alice already knows everything that leads to her current state (`HEAD`), +and reviews what Bob has in his state (`FETCH_HEAD`) that she has not seen with this command. If Alice wants to visualize what Bob did since their histories forked @@ -349,7 +348,7 @@ she can issue the following command: $ gitk HEAD..FETCH_HEAD ------------------------------------------------ -This uses the same two-dot range notation we saw earlier with 'git log'. +This uses the same two-dot range notation we saw earlier with `git log`. Alice may want to view what both of them did since they forked. She can use three-dot form instead of the two-dot form: @@ -361,13 +360,13 @@ $ gitk HEAD...FETCH_HEAD This means "show everything that is reachable from either one, but exclude anything that is reachable from both of them". -Please note that these range notation can be used with both gitk -and "git log". +Please note that these range notation can be used with both `gitk` +and `git log`. After inspecting what Bob did, if there is nothing urgent, Alice may decide to continue working without pulling from Bob. If Bob's history does have something Alice would immediately need, Alice may choose to -stash her work-in-progress first, do a "pull", and then finally unstash +stash her work-in-progress first, do a `pull`, and then finally unstash her work-in-progress on top of the resulting history. When you are working in a small closely knit group, it is not @@ -379,8 +378,8 @@ it easier: alice$ git remote add bob /home/bob/myrepo ------------------------------------------------ -With this, Alice can perform the first part of the "pull" operation -alone using the 'git fetch' command without merging them with her own +With this, Alice can perform the first part of the `pull` operation +alone using the `git fetch` command without merging them with her own branch, using: ------------------------------------- @@ -388,7 +387,7 @@ alice$ git fetch bob ------------------------------------- Unlike the longhand form, when Alice fetches from Bob using a -remote repository shorthand set up with 'git remote', what was +remote repository shorthand set up with `git remote`, what was fetched is stored in a remote-tracking branch, in this case `bob/master`. So after this: @@ -397,10 +396,10 @@ alice$ git log -p master..bob/master ------------------------------------- shows a list of all the changes that Bob made since he branched from -Alice's master branch. +Alice's `master` branch. After examining those changes, Alice -could merge the changes into her master branch: +could merge the changes into her `master` branch: ------------------------------------- alice$ git merge bob/master @@ -432,12 +431,12 @@ bob$ git config --get remote.origin.url /home/alice/project ------------------------------------- -(The complete configuration created by 'git clone' is visible using +(The complete configuration created by `git clone` is visible using `git config -l`, and the linkgit:git-config[1] man page explains the meaning of each option.) -Git also keeps a pristine copy of Alice's master branch under the -name "origin/master": +Git also keeps a pristine copy of Alice's `master` branch under the +name `origin/master`: ------------------------------------- bob$ git branch -r @@ -462,8 +461,8 @@ Exploring history ----------------- Git history is represented as a series of interrelated commits. We -have already seen that the 'git log' command can list those commits. -Note that first line of each git log entry also gives a name for the +have already seen that the `git log` command can list those commits. +Note that first line of each `git log` entry also gives a name for the commit: ------------------------------------- @@ -475,7 +474,7 @@ Date: Tue May 16 17:18:22 2006 -0700 merge-base: Clarify the comments on post processing. ------------------------------------- -We can give this name to 'git show' to see the details about this +We can give this name to `git show` to see the details about this commit. ------------------------------------- @@ -514,7 +513,7 @@ You can also give commits names of your own; after running $ git tag v2.5 1b2e1d63ff ------------------------------------- -you can refer to 1b2e1d63ff by the name "v2.5". If you intend to +you can refer to `1b2e1d63ff` by the name `v2.5`. If you intend to share this name with other people (for example, to identify a release version), you should create a "tag" object, and perhaps sign it; see linkgit:git-tag[1] for details. @@ -533,22 +532,22 @@ $ git reset --hard HEAD^ # reset your current branch and working Be careful with that last command: in addition to losing any changes in the working directory, it will also remove all later commits from this branch. If this branch is the only branch containing those -commits, they will be lost. Also, don't use 'git reset' on a +commits, they will be lost. Also, don't use `git reset` on a publicly-visible branch that other developers pull from, as it will force needless merges on other developers to clean up the history. -If you need to undo changes that you have pushed, use 'git revert' +If you need to undo changes that you have pushed, use `git revert` instead. -The 'git grep' command can search for strings in any version of your +The `git grep` command can search for strings in any version of your project, so ------------------------------------- $ git grep "hello" v2.5 ------------------------------------- -searches for all occurrences of "hello" in v2.5. +searches for all occurrences of "hello" in `v2.5`. -If you leave out the commit name, 'git grep' will search any of the +If you leave out the commit name, `git grep` will search any of the files it manages in your current directory. So ------------------------------------- @@ -558,7 +557,7 @@ $ git grep "hello" is a quick way to search just the files that are tracked by Git. Many Git commands also take sets of commits, which can be specified -in a number of ways. Here are some examples with 'git log': +in a number of ways. Here are some examples with `git log`: ------------------------------------- $ git log v2.5..v2.6 # commits between v2.5 and v2.6 @@ -568,16 +567,16 @@ $ git log v2.5.. Makefile # commits since v2.5 which modify # Makefile ------------------------------------- -You can also give 'git log' a "range" of commits where the first is not +You can also give `git log` a "range" of commits where the first is not necessarily an ancestor of the second; for example, if the tips of -the branches "stable" and "master" diverged from a common +the branches `stable` and `master` diverged from a common commit some time ago, then ------------------------------------- $ git log stable..master ------------------------------------- -will list commits made in the master branch but not in the +will list commits made in the `master` branch but not in the stable branch, while ------------------------------------- @@ -585,15 +584,15 @@ $ git log master..stable ------------------------------------- will show the list of commits made on the stable branch but not -the master branch. +the `master` branch. -The 'git log' command has a weakness: it must present commits in a +The `git log` command has a weakness: it must present commits in a list. When the history has lines of development that diverged and -then merged back together, the order in which 'git log' presents +then merged back together, the order in which `git log` presents those commits is meaningless. Most projects with multiple contributors (such as the Linux kernel, -or Git itself) have frequent merges, and 'gitk' does a better job of +or Git itself) have frequent merges, and `gitk` does a better job of visualizing their history. For example, ------------------------------------- @@ -601,7 +600,7 @@ $ gitk --since="2 weeks ago" drivers/ ------------------------------------- allows you to browse any commits from the last 2 weeks of commits -that modified files under the "drivers" directory. (Note: you can +that modified files under the `drivers` directory. (Note: you can adjust gitk's fonts by holding down the control key while pressing "-" or "+".) @@ -613,7 +612,7 @@ of the file: $ git diff v2.5:Makefile HEAD:Makefile.in ------------------------------------- -You can also use 'git show' to see any such file: +You can also use `git show` to see any such file: ------------------------------------- $ git show v2.5:Makefile @@ -649,7 +648,7 @@ digressions that may be interesting at this point are: * linkgit:git-bisect[1]: When there is a regression in your project, one way to track down the bug is by searching through - the history to find the exact commit that's to blame. Git bisect + the history to find the exact commit that's to blame. `git bisect` can help you perform a binary search for that commit. It is smart enough to perform a close-to-optimal search even in the case of complex non-linear history with lots of merged branches. diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl index a9c7ec69f4..beb5ff8ec2 100644 --- a/Documentation/manpage-normal.xsl +++ b/Documentation/manpage-normal.xsl @@ -8,19 +8,7 @@ <xsl:param name="man.output.quietly" select="1"/> <xsl:param name="refentry.meta.get.quietly" select="1"/> -<!-- convert asciidoc callouts to man page format --> -<xsl:template match="co"> - <xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/> -</xsl:template> -<xsl:template match="calloutlist"> - <xsl:text>.sp </xsl:text> - <xsl:apply-templates/> - <xsl:text> </xsl:text> -</xsl:template> -<xsl:template match="callout"> - <xsl:value-of select="concat('\fB',substring-after(@arearefs,'-'),'. \fR')"/> - <xsl:apply-templates/> - <xsl:text>.br </xsl:text> -</xsl:template> +<!-- unset maximum length of title --> +<xsl:param name="man.th.title.max.length"/> </xsl:stylesheet> |