diff options
Diffstat (limited to 'Documentation')
26 files changed, 578 insertions, 162 deletions
diff --git a/Documentation/RelNotes/2.4.5.txt b/Documentation/RelNotes/2.4.5.txt new file mode 100644 index 0000000000..568297ccb7 --- /dev/null +++ b/Documentation/RelNotes/2.4.5.txt @@ -0,0 +1,28 @@ +Git v2.4.5 Release Notes +======================== + +Fixes since v2.4.4 +------------------ + + * The setup code used to die when core.bare and core.worktree are set + inconsistently, even for commands that do not need working tree. + + * There was a dead code that used to handle "git pull --tags" and + show special-cased error message, which was made irrelevant when + the semantics of the option changed back in Git 1.9 days. + + * "color.diff.plain" was a misnomer; give it 'color.diff.context' as + a more logical synonym. + + * The configuration reader/writer uses mmap(2) interface to access + the files; when we find a directory, it barfed with "Out of memory?". + + * Recent "git prune" traverses young unreachable objects to safekeep + old objects in the reachability chain from them, which sometimes + showed unnecessary error messages that are alarming. + + * "git rebase -i" fired post-rewrite hook when it shouldn't (namely, + when it was told to stop sequencing with 'exec' insn). + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.4.6.txt b/Documentation/RelNotes/2.4.6.txt new file mode 100644 index 0000000000..b53f353939 --- /dev/null +++ b/Documentation/RelNotes/2.4.6.txt @@ -0,0 +1,23 @@ +Git v2.4.6 Release Notes +======================== + +Fixes since v2.4.5 +------------------ + + * "git fetch --depth=<depth>" and "git clone --depth=<depth>" issued + a shallow transfer request even to an upload-pack that does not + support the capability. + + * "git fsck" used to ignore missing or invalid objects recorded in reflog. + + * The tcsh completion writes a bash scriptlet but that would have + failed for users with noclobber set. + + * Recent Mac OS X updates breaks the logic to detect that the machine + is on the AC power in the sample pre-auto-gc script. + + * "git format-patch --ignore-if-upstream A..B" did not like to be fed + tags as boundary commits. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.4.7.txt b/Documentation/RelNotes/2.4.7.txt new file mode 100644 index 0000000000..b3ac412b82 --- /dev/null +++ b/Documentation/RelNotes/2.4.7.txt @@ -0,0 +1,53 @@ +Git v2.4.7 Release Notes +======================== + +Fixes since v2.4.6 +------------------ + + * A minor regression to "git fsck" in v2.2 era was fixed; it + complained about a body-less tag object when it lacked a + separator empty line after its header to separate it with a + non-existent body. + + * We used to ask libCURL to use the most secure authentication method + available when talking to an HTTP proxy only when we were told to + talk to one via configuration variables. We now ask libCURL to + always use the most secure authentication method, because the user + can tell libCURL to use an HTTP proxy via an environment variable + without using configuration variables. + + * When you say "!<ENTER>" while running say "git log", you'd confuse + yourself in the resulting shell, that may look as if you took + control back to the original shell you spawned "git log" from but + that isn't what is happening. To that new shell, we leaked + GIT_PAGER_IN_USE environment variable that was meant as a local + communication between the original "Git" and subprocesses that was + spawned by it after we launched the pager, which caused many + "interesting" things to happen, e.g. "git diff | cat" still paints + its output in color by default. + + Stop leaking that environment variable to the pager's half of the + fork; we only need it on "Git" side when we spawn the pager. + + * Avoid possible ssize_t to int truncation. + + * "git config" failed to update the configuration file when the + underlying filesystem is incapable of renaming a file that is still + open. + + * A minor bugfix when pack bitmap is used with "rev-list --count". + + * An ancient test framework enhancement to allow color was not + entirely correct; this makes it work even when tput needs to read + from the ~/.terminfo under the user's real HOME directory. + + * Fix a small bug in our use of umask() return value. + + * "git rebase" did not exit with failure when format-patch it invoked + failed for whatever reason. + + * Disable "have we lost a race with competing repack?" check while + receiving a huge object transfer that runs index-pack. + +Also contains typofixes, documentation updates and trivial code +clean-ups. diff --git a/Documentation/RelNotes/2.5.0.txt b/Documentation/RelNotes/2.5.0.txt index e39f327341..87044504c5 100644 --- a/Documentation/RelNotes/2.5.0.txt +++ b/Documentation/RelNotes/2.5.0.txt @@ -4,9 +4,6 @@ Git 2.5 Release Notes Updates since v2.4 ------------------ -Ports - - UI, Workflows & Features * The bash completion script (in contrib/) learned a few options that @@ -28,6 +25,8 @@ UI, Workflows & Features chunks from Perforce, instead of making one call to "p4 changes" that may trigger "too many rows scanned" error from Perforce. + * More workaround for Perforce's row number limit in "git p4". + * Unlike "$EDITOR" and "$GIT_EDITOR" that can hold the path to the command and initial options (e.g. "/path/to/emacs -nw"), 'git p4' did not let the shell interpolate the contents of the environment @@ -47,11 +46,14 @@ UI, Workflows & Features rely on symbolic links and make sharing of objects and refs safer by making the borrowee and borrowers aware of each other. + Consider this as still an experimental feature; its UI is still + likely to change. + * Tweak the sample "store" backend of the credential helper to honor XDG configuration file locations when specified. - * A heuristic to help the "git <cmd> <revs> <pathspec>" command line - convention to catch mistyped paths is to make sure all the non-rev + * A heuristic we use to catch mistyped paths on the command line + "git <cmd> <revs> <pathspec>" is to make sure that all the non-rev parameters in the later part of the command line are names of the files in the working tree, but that means "git grep $str -- \*.c" must always be disambiguated with "--", because nobody sane will @@ -64,25 +66,18 @@ UI, Workflows & Features that are not marked as "not-for-merge"; this allows us to lose an old style invocation "git merge <msg> HEAD $commits..." in the implementation of "git pull" script; the old style syntax can now - be deprecated. - - * Help us to find broken test script that splits the body part of the - test by mistaken use of wrong kind of quotes. - (merge d93d5d5 jc/test-prereq-validate later to maint). - - * Developer support to automatically detect broken &&-chain in the - test scripts is now turned on by default. - (merge 92b269f jk/test-chain-lint later to maint). + be deprecated (but not removed yet). * Filter scripts were run with SIGPIPE disabled on the Git side, expecting that they may not read what Git feeds them to filter. We however treated a filter that does not read its input fully - before exiting as an error. + before exiting as an error. We no longer do and ignore EPIPE + when writing to feed the filter scripts. This changes semantics, but arguably in a good way. If a filter - can produce its output without consuming its input using whatever - magic, we now let it do so, instead of diagnosing it as a - programming error. + can produce its output without fully consuming its input using + whatever magic, we now let it do so, instead of diagnosing it + as a programming error. * Instead of dying immediately upon failing to obtain a lock, the locking (of refs etc) retries after a short while with backoff. @@ -98,8 +93,8 @@ UI, Workflows & Features when pushing, but the documentation and help text pretended as if it did. - * The Git subcommand completion (in contrib/) listed credential - helpers among candidates, which is not something the end user would + * The Git subcommand completion (in contrib/) no longer lists credential + helpers among candidates; they are not something the end user would invoke interactively. * The index file can be taught with "update-index --untracked-cache" @@ -120,8 +115,39 @@ UI, Workflows & Features behaves as if HEAD:Documentation/RelNotes/2.5.0.txt was given as input instead. + Consider this as still an experimental and incomplete feature: + + - We may want to do the same for in-index objects, e.g. + asking for :RelNotes with this option should give + :Documentation/RelNotes/2.5.0.txt, too + + - "git cat-file --follow-symlinks blob HEAD:RelNotes" + may also be something we want to allow in the future. + * "git send-email" learned the alias file format used by the sendmail - program (in an abbreviated form). + program (in a simplified form; we obviously do not feed pipes). + + * Traditionally, external low-level 3-way merge drivers are expected + to produce their results based solely on the contents of the three + variants given in temporary files named by %O, %A and %B on their + command line. Additionally allow them to look at the final path + (given by %P). + + * "git blame" learned blame.showEmail configuration variable. + + * "git apply" cannot diagnose a patch corruption when the breakage is + to mark the length of the hunk shorter than it really is on the + hunk header line "@@ -l,k +m,n @@"; one special case it could is + when the hunk becomes no-op (e.g. k == n == 2 for two-line context + patch output), and it learned to do so in this special case. + + * Add the "--allow-unknown-type" option to "cat-file" to allow + inspecting loose objects of an experimental or a broken type. + + * Many long-running operations show progress eye-candy, even when + they are later backgrounded. Hide the eye-candy when the process + is sent to the background instead. + (merge a4fb76c lm/squelch-bg-progress later to maint). Performance, Internal Implementation, Development Support etc. @@ -132,9 +158,11 @@ Performance, Internal Implementation, Development Support etc. but hopefully will give us one extra level of abstraction in the end, when completed. + * for_each_ref() callback functions were taught to name the objects + not with "unsigned char sha1[20]" but with "struct object_id". + * Catch a programmer mistake to feed a pointer not an array to ARRAY_SIZE() macro, by using a couple of GCC extensions. - (merge 89c855e ep/do-not-feed-a-pointer-to-array-size later to maint). * Some error messages in "git config" were emitted without calling the usual error() facility. @@ -152,33 +180,36 @@ Performance, Internal Implementation, Development Support etc. * An earlier rewrite to use strbuf_getwholeline() instead of fgets(3) to read packed-refs file revealed that the former is unacceptably - inefficient. + inefficient. It has been optimized by using getdelim(3) when + available. * The refs API uses ref_lock struct which had its own "int fd", even though the same file descriptor was in the lock struct it contains. Clean-up the code to lose this redundant field. - * Add the "--allow-unknown-type" option to "cat-file" to allow - inspecting loose objects of an experimental or a broken type. - - * Many long-running operations show progress eye-candy, even when - they are later backgrounded. Hide the eye-candy when the process - is sent to the background instead. - (merge 9a9a41d lm/squelch-bg-progress later to maint). - * There was a dead code that used to handle "git pull --tags" and show special-cased error message, which was made irrelevant when the semantics of the option changed back in Git 1.9 days. (merge 19d122b pt/pull-tags-error-diag later to maint). - * for_each_ref() callback functions were taught to name the objects - not with "unsigned char sha1[20]" but with "struct object_id". + * Help us to find broken test script that splits the body part of the + test by mistaken use of wrong kind of quotes. + (merge d93d5d5 jc/test-prereq-validate later to maint). + + * Developer support to automatically detect broken &&-chain in the + test scripts is now turned on by default. + (merge 92b269f jk/test-chain-lint later to maint). * Error reporting mechanism used in "refs" API has been made more consistent. * "git pull" has more test coverage now. + * "git pull" has become more aware of the options meant for + underlying "git fetch" and then learned to use parse-options + parser. + + * Clarify in the Makefile a guideline to decide use of USE_NSEC. Also contains various documentation updates and code clean-ups. @@ -200,7 +231,7 @@ notes for details). * Memory usage of "git index-pack" has been trimmed by tens of per-cent. - (merge a78c5b3 nd/slim-index-pack-memory-usage later to maint). + (merge f0e7f11 nd/slim-index-pack-memory-usage later to maint). * "git rev-list --objects $old --not --all" to see if everything that is reachable from $old is already connected to the existing refs @@ -289,12 +320,6 @@ notes for details). anywhere in the path (e.g. "/home/me/bin/uplink/ssh"). (merge baaf233 bc/connect-plink later to maint). - * "git stash pop/apply" forgot to make sure that not just the working - tree is clean but also the index is clean. The latter is important - as a stash application can conflict and the index will be used for - conflict resolution. - (merge ed178ef jk/stash-require-clean-index later to maint). - * We have prepended $GIT_EXEC_PATH and the path "git" is installed in (typically "/usr/bin") to $PATH when invoking subprograms and hooks for almost eternity, but the original use case the latter tried to @@ -314,19 +339,6 @@ notes for details). the order was swapped from the beginning. This belatedly fixes it. (merge 099d2d8 jc/gitignore-precedence later to maint). - * After "git add -N", the path appeared in output of "git diff HEAD" - and "git diff --cached HEAD", leading "git status" to classify it - as "Changes to be committed". Such a path, however, is not yet to - be scheduled to be committed. "git diff" showed the change to the - path as modification, not as a "new file", in the header of its - output. - - Treat such paths as "yet to be added to the index but Git already - know about them"; "git diff HEAD" and "git diff --cached HEAD" - should not talk about them, and "git diff" should show them as new - files yet to be added to the index. - (merge d95d728 nd/diff-i-t-a later to maint). - * There was a commented-out (instead of being marked to expect failure) test that documented a breakage that was fixed since the test was written; turn it into a proper test. @@ -422,6 +434,98 @@ notes for details). inconsistently, even for commands that do not need working tree. (merge fada767 jk/die-on-bogus-worktree-late later to maint). + * Recent Mac OS X updates breaks the logic to detect that the machine + is on the AC power in the sample pre-auto-gc script. + (merge c54c7b3 pa/auto-gc-mac-osx later to maint). + + * "git commit --cleanup=scissors" was not careful enough to protect + against getting fooled by a line that looked like scissors. + (merge fbfa097 sg/commit-cleanup-scissors later to maint). + + * "Have we lost a race with competing repack?" check was too + expensive, especially while receiving a huge object transfer + that runs index-pack (e.g. "clone" or "fetch"). + (merge 0eeb077 jk/index-pack-reduce-recheck later to maint). + + * The tcsh completion writes a bash scriptlet but that would have + failed for users with noclobber set. + (merge 0b1f688 af/tcsh-completion-noclobber later to maint). + + * "git for-each-ref" reported "missing object" for 0{40} when it + encounters a broken ref. The lack of object whose name is 0{40} is + not the problem; the ref being broken is. + (merge 501cf47 mh/reporting-broken-refs-from-for-each-ref later to maint). + + * Various fixes around "git am" that applies a patch to a history + that is not there yet. + (merge 6ea3b67 pt/am-abort-fix later to maint). + + * "git fsck" used to ignore missing or invalid objects recorded in reflog. + (merge 19bf6c9 mh/fsck-reflog-entries later to maint). + + * "git format-patch --ignore-if-upstream A..B" did not like to be fed + tags as boundary commits. + (merge 9b7a61d jc/do-not-feed-tags-to-clear-commit-marks later to maint). + + * "git fetch --depth=<depth>" and "git clone --depth=<depth>" issued + a shallow transfer request even to an upload-pack that does not + support the capability. + (merge eb86a50 me/fetch-into-shallow-safety later to maint). + + * "git rebase" did not exit with failure when format-patch it invoked + failed for whatever reason. + (merge 60d708b cb/rebase-am-exit-code later to maint). + + * Fix a small bug in our use of umask() return value. + (merge 3096b2e jk/fix-refresh-utime later to maint). + + * An ancient test framework enhancement to allow color was not + entirely correct; this makes it work even when tput needs to read + from the ~/.terminfo under the user's real HOME directory. + (merge d5c1b7c rh/test-color-avoid-terminfo-in-original-home later to maint). + + * A minor bugfix when pack bitmap is used with "rev-list --count". + (merge c8a70d3 jk/rev-list-no-bitmap-while-pruning later to maint). + + * "git config" failed to update the configuration file when the + underlying filesystem is incapable of renaming a file that is still + open. + (merge 7a64592 kb/config-unmap-before-renaming later to maint). + + * Avoid possible ssize_t to int truncation. + (merge 6c8afe4 mh/strbuf-read-file-returns-ssize-t later to maint). + + * When you say "!<ENTER>" while running say "git log", you'd confuse + yourself in the resulting shell, that may look as if you took + control back to the original shell you spawned "git log" from but + that isn't what is happening. To that new shell, we leaked + GIT_PAGER_IN_USE environment variable that was meant as a local + communication between the original "Git" and subprocesses that was + spawned by it after we launched the pager, which caused many + "interesting" things to happen, e.g. "git diff | cat" still paints + its output in color by default. + + Stop leaking that environment variable to the pager's half of the + fork; we only need it on "Git" side when we spawn the pager. + (merge 124b519 jc/unexport-git-pager-in-use-in-pager later to maint). + + * Abandoning an already applied change in "git rebase -i" with + "--continue" left CHERRY_PICK_HEAD and confused later steps. + (merge 0e0aff4 js/rebase-i-clean-up-upon-continue-to-skip later to maint). + + * We used to ask libCURL to use the most secure authentication method + available when talking to an HTTP proxy only when we were told to + talk to one via configuration variables. We now ask libCURL to + always use the most secure authentication method, because the user + can tell libCURL to use an HTTP proxy via an environment variable + without using configuration variables. + (merge 5841520 et/http-proxyauth later to maint). + + * A fix to a minor regression to "git fsck" in v2.2 era that started + complaining about a body-less tag object when it lacks a separator + empty line after its header to separate it with a non-existent body. + (merge 84d18c0 jc/fsck-retire-require-eoh later to maint). + * Code cleanups and documentation updates. (merge 0269f96 mm/usage-log-l-can-take-regex later to maint). (merge 64f2589 nd/t1509-chroot-test later to maint). @@ -443,3 +547,17 @@ notes for details). (merge 055c7e9 sb/pack-protocol-mention-smart-http later to maint). (merge 7c37a5d jk/make-fix-dependencies later to maint). (merge fc0aa39 sg/merge-summary-config later to maint). + (merge 329af6c pt/t0302-needs-sanity later to maint). + (merge d614f07 fk/doc-format-patch-vn later to maint). + (merge 72dbb36 sg/completion-commit-cleanup later to maint). + (merge e654eb2 es/utf8-stupid-compiler-workaround later to maint). + (merge 34b935c es/osx-header-pollutes-mask-macro later to maint). + (merge ab7fade jc/prompt-document-ps1-state-separator later to maint). + (merge 25f600e mm/describe-doc later to maint). + (merge 83fe167 mm/branch-doc-updates later to maint). + (merge 75d2e5a ls/hint-rev-list-count later to maint). + (merge edc8f71 cb/subtree-tests-update later to maint). + (merge 5330e6e sb/p5310-and-chain later to maint). + (merge c4ac525 tb/checkout-doc later to maint). + (merge e479c5f jk/pretty-encoding-doc later to maint). + (merge 7e837c6 ss/clone-guess-dir-name-simplify later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index 18cc592e5c..9358f4c16b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -2180,6 +2180,11 @@ rebase.autoStash:: successful rebase might result in non-trivial conflicts. Defaults to false. +rebase.instructionFormat + A format string, as specified in linkgit:git-log[1], to be used for + the instruction list during an interactive rebase. The format will automatically + have the long commit hash prepended to the format. + receive.advertiseAtomic:: By default, git-receive-pack will advertise the atomic push capability to its clients. If you don't want to this capability diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 9f23a861ce..e6e947c808 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -76,6 +76,8 @@ include::blame-options.txt[] -e:: --show-email:: Show the author email instead of author name (Default: off). + This can also be controlled via the `blame.showEmail` config + option. -w:: Ignore whitespace when comparing the parent's version and diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 359619b552..a67138a022 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -81,7 +81,7 @@ OPTIONS `--track` or `--set-upstream`. -D:: - Delete a branch irrespective of its merged status. + Shortcut for `--delete --force`. -l:: --create-reflog:: @@ -95,13 +95,17 @@ OPTIONS --force:: Reset <branchname> to <startpoint> if <branchname> exists already. Without `-f` 'git branch' refuses to change an existing branch. + In combination with `-d` (or `--delete`), allow deleting the + branch irrespective of its merged status. In combination with + `-m` (or `--move`), allow renaming the branch even if the new + branch name already exists. -m:: --move:: Move/rename a branch and the corresponding reflog. -M:: - Move/rename a branch even if the new branch name already exists. + Shortcut for `--move --force`. --color[=<when>]:: Color branches to highlight current, local, and diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index d263a5652f..63b739c550 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -3,7 +3,7 @@ git-checkout(1) NAME ---- -git-checkout - Checkout a branch or paths to the working tree +git-checkout - Switch branches or restore working tree files SYNOPSIS -------- @@ -89,6 +89,10 @@ Omitting <branch> detaches HEAD at the tip of the current branch. (i.e. commit, tag or tree) to update the index for the given paths before updating the working tree. + +'git checkout' with <paths> or `--patch` is used to restore modified or +deleted paths to their original contents from the index or replace paths +with the contents from a named <tree-ish> (most often a commit-ish). ++ The index may contain unmerged entries because of a previous failed merge. By default, if you try to check out such an entry from the index, the checkout operation will fail and nothing will be checked out. @@ -225,13 +229,6 @@ This means that you can use `git checkout -p` to selectively discard edits from your current working tree. See the ``Interactive Mode'' section of linkgit:git-add[1] to learn how to operate the `--patch` mode. ---to=<path>:: - Check out a branch in a separate working directory at - `<path>`. A new working directory is linked to the current - repository, sharing everything except working directory - specific files such as HEAD, index... See "MULTIPLE WORKING - TREES" section for more information. - --ignore-other-worktrees:: `git checkout` refuses when the wanted ref is already checked out by another worktree. This option makes it check the ref @@ -401,71 +398,6 @@ $ git reflog -2 HEAD # or $ git log -g -2 HEAD ------------ -MULTIPLE WORKING TREES ----------------------- - -A git repository can support multiple working trees, allowing you to check -out more than one branch at a time. With `git checkout --to` a new working -tree is associated with the repository. This new working tree is called a -"linked working tree" as opposed to the "main working tree" prepared by "git -init" or "git clone". A repository has one main working tree (if it's not a -bare repository) and zero or more linked working trees. - -Each linked working tree has a private sub-directory in the repository's -$GIT_DIR/worktrees directory. The private sub-directory's name is usually -the base name of the linked working tree's path, possibly appended with a -number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the -command `git checkout --to /path/other/test-next next` creates the linked -working tree in `/path/other/test-next` and also creates a -`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1` -if `test-next` is already taken). - -Within a linked working tree, $GIT_DIR is set to point to this private -directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and -$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR -(e.g. `/path/main/.git`). These settings are made in a `.git` file located at -the top directory of the linked working tree. - -Path resolution via `git rev-parse --git-path` uses either -$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the -linked working tree `git rev-parse --git-path HEAD` returns -`/path/main/.git/worktrees/test-next/HEAD` (not -`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git -rev-parse --git-path refs/heads/master` uses -$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`, -since refs are shared across all working trees. - -See linkgit:gitrepository-layout[5] for more information. The rule of -thumb is do not make any assumption about whether a path belongs to -$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something -inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. - -When you are done with a linked working tree you can simply delete it. -The working tree's entry in the repository's $GIT_DIR/worktrees -directory will eventually be removed automatically (see -`gc.pruneworktreesexpire` in linkgit::git-config[1]), or you can run -`git prune --worktrees` in the main or any linked working tree to -clean up any stale entries in $GIT_DIR/worktrees. - -If you move a linked working directory to another file system, or -within a file system that does not support hard links, you need to run -at least one git command inside the linked working directory -(e.g. `git status`) in order to update its entry in $GIT_DIR/worktrees -so that it does not get automatically removed. - -To prevent a $GIT_DIR/worktrees entry from from being pruned (which -can be useful in some situations, such as when the -entry's working tree is stored on a portable device), add a file named -'locked' to the entry's directory. The file contains the reason in -plain text. For example, if a linked working tree's `.git` file points -to `/path/main/.git/worktrees/test-next` then a file named -`/path/main/.git/worktrees/test-next/locked` will prevent the -`test-next` entry from being pruned. See -linkgit:gitrepository-layout[5] for details. - -Multiple checkout support for submodules is incomplete. It is NOT -recommended to make multiple checkouts of a superproject. - EXAMPLES -------- diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index d20ca402a1..e045fc73f8 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -3,7 +3,7 @@ git-describe(1) NAME ---- -git-describe - Show the most recent tag that is reachable from a commit +git-describe - Describe a commit using the most recent tag reachable from it SYNOPSIS diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index bb3ea9372f..0dac4e9b86 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -170,7 +170,7 @@ will want to ensure that threading is disabled for `git send-email`. -v <n>:: --reroll-count=<n>:: Mark the series as the <n>-th iteration of the topic. The - output filenames have `v<n>` pretended to them, and the + output filenames have `v<n>` prepended to them, and the subject prefix ("PATCH" by default, but configurable via the `--subject-prefix` option) has ` v<n>` appended to it. E.g. `--reroll-count=4` may produce `v4-0001-add-makefile.patch` diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 1cf3bed4ab..7a493c80f7 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -48,9 +48,6 @@ OPTIONS --expire <time>:: Only expire loose objects older than <time>. ---worktrees:: - Prune dead working tree information in $GIT_DIR/worktrees. - <head>...:: In addition to objects reachable from any of our references, keep objects diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 712ab4baed..93c72a29ce 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -74,9 +74,6 @@ pulling or stash them away with linkgit:git-stash[1]. OPTIONS ------- -Options meant for 'git pull' itself and the underlying 'git merge' -must be given before the options meant for 'git fetch'. - -q:: --quiet:: This is passed to both underlying git-fetch to squelch reporting of diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 1d01baa5fc..7dc613cf3e 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -213,6 +213,9 @@ rebase.autoSquash:: rebase.autoStash:: If set to true enable '--autostash' option by default. +rebase.instructionFormat:: + Custom commit list format to use during an '--interactive' rebase. + OPTIONS ------- --onto <newbase>:: @@ -359,6 +362,10 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`. Make a list of the commits which are about to be rebased. Let the user edit that list before rebasing. This mode can also be used to split commits (see SPLITTING COMMITS below). ++ +The commit list format can be changed by setting the configuration option +rebase.instructionFormat. A customized instruction format will automatically +have the long commit hash prepended to the format. -p:: --preserve-merges:: diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index b10ea60833..7b49c85347 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -56,6 +56,7 @@ SYNOPSIS [ --reverse ] [ --walk-reflogs ] [ --no-walk ] [ --do-walk ] + [ --count ] [ --use-bitmap-index ] <commit>... [ \-- <paths>... ] diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index b48a764320..f14705ee04 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -49,17 +49,17 @@ Composing of 'sendemail.annotate'. See the CONFIGURATION section for 'sendemail.multiEdit'. ---bcc=<address>:: +--bcc=<address>,...:: Specify a "Bcc:" value for each email. Default is the value of 'sendemail.bcc'. + -The --bcc option must be repeated for each user you want on the bcc list. +This option may be specified multiple times. ---cc=<address>:: +--cc=<address>,...:: Specify a starting "Cc:" value for each email. Default is the value of 'sendemail.cc'. + -The --cc option must be repeated for each user you want on the cc list. +This option may be specified multiple times. --compose:: Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1]) @@ -110,13 +110,13 @@ is not set, this will be prompted for. Only necessary if --compose is also set. If --compose is not set, this will be prompted for. ---to=<address>:: +--to=<address>,...:: Specify the primary recipient of the emails generated. Generally, this will be the upstream maintainer of the project involved. Default is the value of the 'sendemail.to' configuration value; if that is unspecified, and --to-cmd is not specified, this will be prompted for. + -The --to option must be repeated for each user you want on the to list. +This option may be specified multiple times. --8bit-encoding=<encoding>:: When encountering a non-ASCII message or subject that does not @@ -394,8 +394,9 @@ described below: sendmail;; * Quoted aliases and quoted addresses are not supported: lines that contain a `"` symbol are ignored. -* Line continuations are not supported: lines that start with - whitespace characters, or end with a `\` symbol are ignored. +* Redirection to a file (`/path/name`) or pipe (`|command`) is not + supported. +* File inclusion (`:include: /path/name`) is not supported. * Warnings are printed on the standard error output for any explicitly unsupported constructs, and any other lines that are not recognized by the parser. diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt index 9413e2802a..ecf4da16cf 100644 --- a/Documentation/git-verify-commit.txt +++ b/Documentation/git-verify-commit.txt @@ -16,6 +16,10 @@ Validates the gpg signature created by 'git commit -S'. OPTIONS ------- +--raw:: + Print the raw gpg status output to standard error instead of the normal + human-readable output. + -v:: --verbose:: Print the contents of the commit object before validating it. diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index f88ba96f02..d590edcebd 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -16,6 +16,10 @@ Validates the gpg signature created by 'git tag'. OPTIONS ------- +--raw:: + Print the raw gpg status output to standard error instead of the normal + human-readable output. + -v:: --verbose:: Print the contents of the tag object before validating it. diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt new file mode 100644 index 0000000000..3387e2f037 --- /dev/null +++ b/Documentation/git-worktree.txt @@ -0,0 +1,176 @@ +git-worktree(1) +=============== + +NAME +---- +git-worktree - Manage multiple worktrees + + +SYNOPSIS +-------- +[verse] +'git worktree add' [-f] [--detach] [-b <new-branch>] <path> [<branch>] +'git worktree prune' [-n] [-v] [--expire <expire>] + +DESCRIPTION +----------- + +Manage multiple worktrees attached to the same repository. + +A git repository can support multiple working trees, allowing you to check +out more than one branch at a time. With `git worktree add` a new working +tree is associated with the repository. This new working tree is called a +"linked working tree" as opposed to the "main working tree" prepared by "git +init" or "git clone". A repository has one main working tree (if it's not a +bare repository) and zero or more linked working trees. + +When you are done with a linked working tree you can simply delete it. +The working tree's administrative files in the repository (see +"DETAILS" below) will eventually be removed automatically (see +`gc.pruneworktreesexpire` in linkgit::git-config[1]), or you can run +`git worktree prune` in the main or any linked working tree to +clean up any stale administrative files. + +If you move a linked working directory to another file system, or +within a file system that does not support hard links, you need to run +at least one git command inside the linked working directory +(e.g. `git status`) in order to update its administrative files in the +repository so that they do not get automatically pruned. + +If a linked working tree is stored on a portable device or network share +which is not always mounted, you can prevent its administrative files from +being pruned by creating a file named 'lock' alongside the other +administrative files, optionally containing a plain text reason that +pruning should be suppressed. See section "DETAILS" for more information. + +COMMANDS +-------- +add <path> [<branch>]:: + +Create `<path>` and checkout `<branch>` into it. The new working directory +is linked to the current repository, sharing everything except working +directory specific files such as HEAD, index, etc. ++ +If `<branch>` is omitted and neither `-b` nor `-B` is used, then, as a +convenience, a new branch based at HEAD is created automatically, as if +`-b $(basename <path>)` was specified. + +prune:: + +Prune working tree information in $GIT_DIR/worktrees. + +OPTIONS +------- + +-f:: +--force:: + By default, `add` refuses to create a new worktree when `<branch>` + is already checked out by another worktree. This option overrides + that safeguard. + +-b <new-branch>:: +-B <new-branch>:: + With `add`, create a new branch named `<new-branch>` starting at + `<branch>`, and check out `<new-branch>` into the new worktree. + If `<branch>` is omitted, it defaults to HEAD. + By default, `-b` refuses to create a new branch if it already + exists. `-B` overrides this safeguard, resetting `<new-branch>` to + `<branch>`. + +--detach:: + With `add`, detach HEAD in the new worktree. See "DETACHED HEAD" in + linkgit:git-checkout[1]. + +-n:: +--dry-run:: + With `prune`, do not remove anything; just report what it would + remove. + +-v:: +--verbose:: + With `prune`, report all removals. + +--expire <time>:: + With `prune`, only expire unused worktrees older than <time>. + +DETAILS +------- +Each linked working tree has a private sub-directory in the repository's +$GIT_DIR/worktrees directory. The private sub-directory's name is usually +the base name of the linked working tree's path, possibly appended with a +number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the +command `git worktree add /path/other/test-next next` creates the linked +working tree in `/path/other/test-next` and also creates a +`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1` +if `test-next` is already taken). + +Within a linked working tree, $GIT_DIR is set to point to this private +directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and +$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR +(e.g. `/path/main/.git`). These settings are made in a `.git` file located at +the top directory of the linked working tree. + +Path resolution via `git rev-parse --git-path` uses either +$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the +linked working tree `git rev-parse --git-path HEAD` returns +`/path/main/.git/worktrees/test-next/HEAD` (not +`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git +rev-parse --git-path refs/heads/master` uses +$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`, +since refs are shared across all working trees. + +See linkgit:gitrepository-layout[5] for more information. The rule of +thumb is do not make any assumption about whether a path belongs to +$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something +inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. + +To prevent a $GIT_DIR/worktrees entry from from being pruned (which +can be useful in some situations, such as when the +entry's working tree is stored on a portable device), add a file named +'locked' to the entry's directory. The file contains the reason in +plain text. For example, if a linked working tree's `.git` file points +to `/path/main/.git/worktrees/test-next` then a file named +`/path/main/.git/worktrees/test-next/locked` will prevent the +`test-next` entry from being pruned. See +linkgit:gitrepository-layout[5] for details. + +EXAMPLES +-------- +You are in the middle of a refactoring session and your boss comes in and +demands that you fix something immediately. You might typically use +linkgit:git-stash[1] to store your changes away temporarily, however, your +worktree is in such a state of disarray (with new, moved, and removed files, +and other bits and pieces strewn around) that you don't want to risk +disturbing any of it. Instead, you create a temporary linked worktree to +make the emergency fix, remove it when done, and then resume your earlier +refactoring session. + +------------ +$ git worktree add -b emergency-fix ../temp master +$ pushd ../temp +# ... hack hack hack ... +$ git commit -a -m 'emergency fix for boss' +$ popd +$ rm -rf ../temp +$ git worktree prune +------------ + +BUGS +---- +Multiple checkout in general is still experimental, and the support +for submodules is incomplete. It is NOT recommended to make multiple +checkouts of a superproject. + +git-worktree could provide more automation for tasks currently +performed manually, such as: + +- `remove` to remove a linked worktree and its administrative files (and + warn if the worktree is dirty) +- `mv` to move or rename a worktree and update its administrative files +- `list` to list linked worktrees +- `lock` to prevent automatic pruning of administrative files (for instance, + for a worktree on a portable device) + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git.txt b/Documentation/git.txt index dfbc2290c0..f87d3325f8 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,17 @@ unreleased) version of Git, that is available from the 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v2.4.4/git.html[documentation for release 2.4.4] +* link:v2.5.0/git.html[documentation for release 2.5] * release notes for + link:RelNotes/2.5.0.txt[2.5], + +* link:v2.4.7/git.html[documentation for release 2.4.7] + +* release notes for + link:RelNotes/2.4.7.txt[2.4.7], + link:RelNotes/2.4.6.txt[2.4.6], + link:RelNotes/2.4.5.txt[2.4.5], link:RelNotes/2.4.4.txt[2.4.4], link:RelNotes/2.4.3.txt[2.4.3], link:RelNotes/2.4.2.txt[2.4.2], @@ -843,7 +851,7 @@ Git so take care if using Cogito etc. normally in $GIT_DIR will be taken from this path instead. Worktree-specific files such as HEAD or index are taken from $GIT_DIR. See linkgit:gitrepository-layout[5] and - the section 'MULTIPLE CHECKOUT MODE' in linkgit:checkout[1] + linkgit:git-worktree[1] for details. This variable has lower precedence than other path variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY... @@ -1001,9 +1009,20 @@ Unsetting the variable, or setting it to empty, "0" or Enables trace messages for all packets coming in or out of a given program. This can help with debugging object negotiation or other protocol issues. Tracing is turned off at a packet - starting with "PACK". + starting with "PACK" (but see 'GIT_TRACE_PACKFILE' below). See 'GIT_TRACE' for available trace output options. +'GIT_TRACE_PACKFILE':: + Enables tracing of packfiles sent or received by a + given program. Unlike other trace output, this trace is + verbatim: no headers, and no quoting of binary data. You almost + certainly want to direct into a file (e.g., + `GIT_TRACE_PACKFILE=/tmp/my.pack`) rather than displaying it on + the terminal or mixing it with other trace output. ++ +Note that this is currently only implemented for the client side +of clones and fetches. + 'GIT_TRACE_PERFORMANCE':: Enables performance related trace messages, e.g. total execution time of each Git command. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 70899b3023..81fe586948 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -774,7 +774,7 @@ To define a custom merge driver `filfre`, add a section to your ---------------------------------------------------------------- [merge "filfre"] name = feel-free merge driver - driver = filfre %O %A %B + driver = filfre %O %A %B %L %P recursive = binary ---------------------------------------------------------------- @@ -800,6 +800,9 @@ merge between common ancestors, when there are more than one. When left unspecified, the driver itself is used for both internal merge and the final merge. +The merge driver can learn the pathname in which the merged result +will be stored via placeholder `%P`. + `conflict-marker-size` ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index a096e7ddf7..8a42270074 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -487,7 +487,7 @@ By default it is set to (), i.e. an empty list. This means that gitweb would not try to create project URL (to fetch) from project name. $projects_list_group_categories:: - Whether to enables the grouping of projects by category on the project + Whether to enable the grouping of projects by category on the project list page. The category of a project is determined by the `$GIT_DIR/category` file or the `gitweb.category` variable in each repository's configuration. Disabled by default (set to 0). diff --git a/Documentation/i18n.txt b/Documentation/i18n.txt index e9a1d5d25a..2dd79db5cb 100644 --- a/Documentation/i18n.txt +++ b/Documentation/i18n.txt @@ -1,18 +1,31 @@ -At the core level, Git is character encoding agnostic. - - - The pathnames recorded in the index and in the tree objects - are treated as uninterpreted sequences of non-NUL bytes. - What readdir(2) returns are what are recorded and compared - with the data Git keeps track of, which in turn are expected - to be what lstat(2) and creat(2) accepts. There is no such - thing as pathname encoding translation. +Git is to some extent character encoding agnostic. - The contents of the blob objects are uninterpreted sequences of bytes. There is no encoding translation at the core level. - - The commit log messages are uninterpreted sequences of non-NUL - bytes. + - Path names are encoded in UTF-8 normalization form C. This + applies to tree objects, the index file, ref names, as well as + path names in command line arguments, environment variables + and config files (`.git/config` (see linkgit:git-config[1]), + linkgit:gitignore[5], linkgit:gitattributes[5] and + linkgit:gitmodules[5]). ++ +Note that Git at the core level treats path names simply as +sequences of non-NUL bytes, there are no path name encoding +conversions (except on Mac and Windows). Therefore, using +non-ASCII path names will mostly work even on platforms and file +systems that use legacy extended ASCII encodings. However, +repositories created on such systems will not work properly on +UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. +Additionally, many Git-based tools simply assume path names to +be UTF-8 and will fail to display other encodings correctly. + + - Commit log messages are typically encoded in UTF-8, but other + extended ASCII encodings are also supported. This includes + ISO-8859-x, CP125x and many others, but _not_ UTF-16/32, + EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, + EUC-x, CP9xx etc.). Although we encourage that the commit log messages are encoded in UTF-8, both the core and Git Porcelain are designed not to diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 74aa01a0ec..642af6e426 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -37,7 +37,10 @@ people using 80-column terminals. in their encoding header; this option can be used to tell the command to re-code the commit log message in the encoding preferred by the user. For non plumbing commands this - defaults to UTF-8. + defaults to UTF-8. Note that if an object claims to be encoded + in `X` and we are outputting in `X`, we will output the object + verbatim; this means that invalid sequences in the original + commit may be copied to the output. --notes[=<ref>]:: Show the notes (see linkgit:git-notes[1]) that annotate the diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index 1a797812fb..8076172a08 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -46,6 +46,9 @@ Functions Format a string and push it onto the end of the array. This is a convenience wrapper combining `strbuf_addf` and `argv_array_push`. +`argv_array_pushv`:: + Push a null-terminated array of strings onto the end of the array. + `argv_array_pop`:: Remove the final element from the array. If there are no elements in the array, do nothing. diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 1f2db31312..5f0757dcc9 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -168,6 +168,12 @@ There are some macros to easily define options: Introduce an option with integer argument. The integer is put into `int_var`. +`OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`:: + Introduce an option with a size argument. The argument must be a + non-negative integer and may include a suffix of 'k', 'm' or 'g' to + scale the provided value by 1024, 1024^2 or 1024^3 respectively. + The scaled value is put into `unsigned_long_var`. + `OPT_DATE(short, long, &int_var, description)`:: Introduce an option with date argument, see `approxidate()`. The timestamp is put into `int_var`. @@ -212,6 +218,19 @@ There are some macros to easily define options: Use it to hide deprecated options that are still to be recognized and ignored silently. +`OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`:: + Introduce an option that will be reconstructed into a char* string, + which must be initialized to NULL. This is useful when you need to + pass the command-line option to another command. Any previous value + will be overwritten, so this should only be used for options where + the last one specified on the command line wins. + +`OPT_PASSTHRU_ARGV(short, long, &argv_array_var, arg_str, description, flags)`:: + Introduce an option where all instances of it on the command-line will + be reconstructed into an argv_array. This is useful when you need to + pass the command-line option, which can be specified multiple times, + to another command. + The last element of the array must be `OPT_END()`. diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index 242a044db9..4a8be4d144 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -41,13 +41,17 @@ With a `USE_STDEV` compile-time option, `st_dev` is also compared, but this is not enabled by default because this member is not stable on network filesystems. With `USE_NSEC` compile-time option, `st_mtim.tv_nsec` and `st_ctim.tv_nsec` -members are also compared, but this is not enabled by default +members are also compared. On Linux, this is not enabled by default because in-core timestamps can have finer granularity than on-disk timestamps, resulting in meaningless changes when an inode is evicted from the inode cache. See commit 8ce13b0 of git://git.kernel.org/pub/scm/linux/kernel/git/tglx/history.git ([PATCH] Sync in core time granularity with filesystems, -2005-01-04). +2005-01-04). This patch is included in kernel 2.6.11 and newer, but +only fixes the issue for file systems with exactly 1 ns or 1 s +resolution. Other file systems are still broken in current Linux +kernels (e.g. CEPH, CIFS, NTFS, UDF), see +https://lkml.org/lkml/2015/6/9/714 Racy Git -------- |