diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/2.10.1.txt | 33 | ||||
| -rw-r--r-- | Documentation/RelNotes/2.9.4.txt | 83 | ||||
| -rw-r--r-- | Documentation/SubmittingPatches | 11 | ||||
| -rw-r--r-- | Documentation/config.txt | 20 | ||||
| -rw-r--r-- | Documentation/git-check-ref-format.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-checkout.txt | 12 | ||||
| -rw-r--r-- | Documentation/gitk.txt | 2 | ||||
| -rw-r--r-- | Documentation/gitrevisions.txt | 6 | ||||
| -rw-r--r-- | Documentation/pretty-formats.txt | 2 | ||||
| -rw-r--r-- | Documentation/rev-list-options.txt | 4 | ||||
| -rw-r--r-- | Documentation/revisions.txt | 125 |
11 files changed, 239 insertions, 63 deletions
diff --git a/Documentation/RelNotes/2.10.1.txt b/Documentation/RelNotes/2.10.1.txt new file mode 100644 index 0000000000..75c07e199e --- /dev/null +++ b/Documentation/RelNotes/2.10.1.txt @@ -0,0 +1,33 @@ +Git v2.10.1 Release Notes +========================= + +Fixes since v2.10 +----------------- + + * Clarify various ways to specify the "revision ranges" in the + documentation. + + * "diff-highlight" script (in contrib/) learned to work better with + "git log -p --graph" output. + + * The test framework left the number of tests and success/failure + count in the t/test-results directory, keyed by the name of the + test script plus the process ID. The latter however turned out not + to serve any useful purpose. The process ID part of the filename + has been removed. + + * Having a submodule whose ".git" repository is somehow corrupt + caused a few commands that recurse into submodules loop forever. + + * "git symbolic-ref -d HEAD" happily removes the symbolic ref, but + the resulting repository becomes an invalid one. Teach the command + to forbid removal of HEAD. + + * A test spawned a short-lived background process, which sometimes + prevented the test directory from getting removed at the end of the + script on some platforms. + + * Update a few tests that used to use GIT_CURL_VERBOSE to use the + newer GIT_TRACE_CURL. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.9.4.txt b/Documentation/RelNotes/2.9.4.txt new file mode 100644 index 0000000000..01e864278b --- /dev/null +++ b/Documentation/RelNotes/2.9.4.txt @@ -0,0 +1,83 @@ +Git v2.9.4 Release Notes +======================== + +Fixes since v2.9.3 +------------------ + + * There are certain house-keeping tasks that need to be performed at + the very beginning of any Git program, and programs that are not + built-in commands had to do them exactly the same way as "git" + potty does. It was easy to make mistakes in one-off standalone + programs (like test helpers). A common "main()" function that + calls cmd_main() of individual program has been introduced to + make it harder to make mistakes. + + * "git merge" with renormalization did not work well with + merge-recursive, due to "safer crlf" conversion kicking in when it + shouldn't. + + * The reflog output format is documented better, and a new format + --date=unix to report the seconds-since-epoch (without timezone) + has been added. + + * "git push --force-with-lease" already had enough logic to allow + ensuring that such a push results in creation of a ref (i.e. the + receiving end did not have another push from sideways that would be + discarded by our force-pushing), but didn't expose this possibility + to the users. It does so now. + + * "import-tars" fast-import script (in contrib/) used to ignore a + hardlink target and replaced it with an empty file, which has been + corrected to record the same blob as the other file the hardlink is + shared with. + + * "git mv dir non-existing-dir/" did not work in some environments + the same way as existing mainstream platforms. The code now moves + "dir" to "non-existing-dir", without relying on rename("A", "B/") + that strips the trailing slash of '/'. + + * The "t/" hierarchy is prone to get an unusual pathname; "make test" + has been taught to make sure they do not contain paths that cannot + be checked out on Windows (and the mechanism can be reusable to + catch pathnames that are not portable to other platforms as need + arises). + + * When "git merge-recursive" works on history with many criss-cross + merges in "verbose" mode, the names the command assigns to the + virtual merge bases could have overwritten each other by unintended + reuse of the same piece of memory. + + * "git checkout --detach <branch>" used to give the same advice + message as that is issued when "git checkout <tag>" (or anything + that is not a branch name) is given, but asking with "--detach" is + an explicit enough sign that the user knows what is going on. The + advice message has been squelched in this case. + + * "git difftool" by default ignores the error exit from the backend + commands it spawns, because often they signal that they found + differences by exiting with a non-zero status code just like "diff" + does; the exit status codes 126 and above however are special in + that they are used to signal that the command is not executable, + does not exist, or killed by a signal. "git difftool" has been + taught to notice these exit status codes. + + * On Windows, help.browser configuration variable used to be ignored, + which has been corrected. + + * The "git -c var[=val] cmd" facility to append a configuration + variable definition at the end of the search order was described in + git(1) manual page, but not in git-config(1), which was more likely + place for people to look for when they ask "can I make a one-shot + override, and if so how?" + + * The tempfile (hence its user lockfile) API lets the caller to open + a file descriptor to a temporary file, write into it and then + finalize it by first closing the filehandle and then either + removing or renaming the temporary file. When the process spawns a + subprocess after obtaining the file descriptor, and if the + subprocess has not exited when the attempt to remove or rename is + made, the last step fails on Windows, because the subprocess has + the file descriptor still open. Open tempfile with O_CLOEXEC flag + to avoid this (on Windows, this is mapped to O_NOINHERIT). + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 500230c054..08352deaae 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -122,9 +122,14 @@ without external resources. Instead of giving a URL to a mailing list archive, summarize the relevant points of the discussion. If you want to reference a previous commit in the history of a stable -branch use the format "abbreviated sha1 (subject, date)". So for example -like this: "Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) -noticed [...]". +branch, use the format "abbreviated sha1 (subject, date)", +with the subject enclosed in a pair of double-quotes, like this: + + Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30) + noticed that ... + +The "Copy commit summary" command of gitk can be used to obtain this +format. (3) Generate your patch using Git tools out of your commits. diff --git a/Documentation/config.txt b/Documentation/config.txt index 0bcb6790d6..a077c64ef0 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -953,7 +953,8 @@ color.branch:: A boolean to enable/disable color in the output of linkgit:git-branch[1]. May be set to `always`, `false` (or `never`) or `auto` (or `true`), in which case colors are used - only when the output is to a terminal. Defaults to false. + only when the output is to a terminal. If unset, then the + value of `color.ui` is used (`auto` by default). color.branch.<slot>:: Use customized color for branch coloration. `<slot>` is one of @@ -968,7 +969,8 @@ color.diff:: linkgit:git-log[1], and linkgit:git-show[1] will use color for all patches. If it is set to `true` or `auto`, those commands will only use color when output is to the terminal. - Defaults to false. + If unset, then the value of `color.ui` is used (`auto` by + default). + This does not affect linkgit:git-format-patch[1] or the 'git-diff-{asterisk}' plumbing commands. Can be overridden on the @@ -991,7 +993,8 @@ color.decorate.<slot>:: color.grep:: When set to `always`, always highlight matches. When `false` (or `never`), never. When set to `true` or `auto`, use color only - when the output is written to the terminal. Defaults to `false`. + when the output is written to the terminal. If unset, then the + value of `color.ui` is used (`auto` by default). color.grep.<slot>:: Use customized color for grep colorization. `<slot>` specifies which @@ -1024,7 +1027,8 @@ color.interactive:: and displays (such as those used by "git-add --interactive" and "git-clean --interactive"). When false (or `never`), never. When set to `true` or `auto`, use colors only when the output is - to the terminal. Defaults to false. + to the terminal. If unset, then the value of `color.ui` is + used (`auto` by default). color.interactive.<slot>:: Use customized color for 'git add --interactive' and 'git clean @@ -1040,13 +1044,15 @@ color.showBranch:: A boolean to enable/disable color in the output of linkgit:git-show-branch[1]. May be set to `always`, `false` (or `never`) or `auto` (or `true`), in which case colors are used - only when the output is to a terminal. Defaults to false. + only when the output is to a terminal. If unset, then the + value of `color.ui` is used (`auto` by default). color.status:: A boolean to enable/disable color in the output of linkgit:git-status[1]. May be set to `always`, `false` (or `never`) or `auto` (or `true`), in which case colors are used - only when the output is to a terminal. Defaults to false. + only when the output is to a terminal. If unset, then the + value of `color.ui` is used (`auto` by default). color.status.<slot>:: Use customized color for status colorization. `<slot>` is @@ -1366,7 +1372,7 @@ fsck.skipList:: gc.aggressiveDepth:: The depth parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults - to 250. + to 50. gc.aggressiveWindow:: The window size parameter used in the delta compression diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index 91a3622ee4..8611a99120 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -118,8 +118,8 @@ $ git check-ref-format --branch @{-1} * Determine the reference name to use for a new branch: + ------------ -$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch") || -die "we do not like '$newbranch' as a branch name." +$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch")|| +{ echo "we do not like '$newbranch' as a branch name." >&2 ; exit 1 ; } ------------ GIT diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 7a2201b051..8e2c0662dd 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -419,6 +419,18 @@ $ git reflog -2 HEAD # or $ git log -g -2 HEAD ------------ +ARGUMENT DISAMBIGUATION +----------------------- + +When there is only one argument given and it is not `--` (e.g. "git +checkout abc"), and when the argument is both a valid `<tree-ish>` +(e.g. a branch "abc" exists) and a valid `<pathspec>` (e.g. a file +or a directory whose name is "abc" exists), Git would usually ask +you to disambiguate. Because checking out a branch is so common an +operation, however, "git checkout abc" takes "abc" as a `<tree-ish>` +in such a situation. Use `git checkout -- <pathspec>` if you want +to checkout these paths out of the index. + EXAMPLES -------- diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index a68d860fa3..e382dd96df 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list. --left-right:: - Mark which side of a symmetric diff a commit is reachable + Mark which side of a symmetric difference a commit is reachable from. Commits from the left side are prefixed with a `<` symbol and those from the right with a `>` symbol. diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt index e903eb7860..27dec5b91d 100644 --- a/Documentation/gitrevisions.txt +++ b/Documentation/gitrevisions.txt @@ -15,9 +15,9 @@ DESCRIPTION Many Git commands take revision parameters as arguments. Depending on the command, they denote a specific commit or, for commands which -walk the revision graph (such as linkgit:git-log[1]), all commits which can -be reached from that commit. In the latter case one can also specify a -range of revisions explicitly. +walk the revision graph (such as linkgit:git-log[1]), all commits which are +reachable from that commit. For commands that walk the revision graph one can +also specify a range of revisions explicitly. In addition, some Git commands (such as linkgit:git-show[1]) also take revision parameters which denote other objects than commits, e.g. blobs diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index b95d67ec01..a942d57f73 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -172,7 +172,7 @@ endif::git-rev-list[] respecting the `auto` settings of the former if we are going to a terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring on the next placeholders until the color is switched again. -- '%m': left, right or boundary mark +- '%m': left (`<`), right (`>`) or boundary (`-`) mark - '%n': newline - '%%': a raw '%' - '%x00': print a byte from a hex code diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index a779c9dfec..7e462d3841 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -225,7 +225,7 @@ excluded from the output. --left-only:: --right-only:: - List only commits on the respective side of a symmetric range, + List only commits on the respective side of a symmetric difference, i.e. only those which would be marked `<` resp. `>` by `--left-right`. + @@ -796,7 +796,7 @@ ifdef::git-rev-list[] endif::git-rev-list[] --left-right:: - Mark which side of a symmetric diff a commit is reachable from. + Mark which side of a symmetric difference a commit is reachable from. Commits from the left side are prefixed with `<` and those from the right with `>`. If combined with `--boundary`, those commits are prefixed with `-`. diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index abae363983..4bed5b1ab7 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -237,48 +237,74 @@ SPECIFYING RANGES ----------------- History traversing commands such as `git log` operate on a set -of commits, not just a single commit. To these commands, -specifying a single revision with the notation described in the -previous section means the set of commits reachable from that -commit, following the commit ancestry chain. - -To exclude commits reachable from a commit, a prefix '{caret}' -notation is used. E.g. '{caret}r1 r2' means commits reachable -from 'r2' but exclude the ones reachable from 'r1'. - -This set operation appears so often that there is a shorthand -for it. When you have two commits 'r1' and 'r2' (named according -to the syntax explained in SPECIFYING REVISIONS above), you can ask -for commits that are reachable from r2 excluding those that are reachable -from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'. - -A similar notation 'r1\...r2' is called symmetric difference -of 'r1' and 'r2' and is defined as -'r1 r2 --not $(git merge-base --all r1 r2)'. -It is the set of commits that are reachable from either one of -'r1' or 'r2' but not from both. - -In these two shorthands, you can omit one end and let it default to HEAD. +of commits, not just a single commit. + +For these commands, +specifying a single revision, using the notation described in the +previous section, means the set of commits `reachable` from the given +commit. + +A commit's reachable set is the commit itself and the commits in +its ancestry chain. + + +Commit Exclusions +~~~~~~~~~~~~~~~~~ + +'{caret}<rev>' (caret) Notation:: + To exclude commits reachable from a commit, a prefix '{caret}' + notation is used. E.g. '{caret}r1 r2' means commits reachable + from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and + its ancestors). + +Dotted Range Notations +~~~~~~~~~~~~~~~~~~~~~~ + +The '..' (two-dot) Range Notation:: + The '{caret}r1 r2' set operation appears so often that there is a shorthand + for it. When you have two commits 'r1' and 'r2' (named according + to the syntax explained in SPECIFYING REVISIONS above), you can ask + for commits that are reachable from r2 excluding those that are reachable + from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'. + +The '...' (three dot) Symmetric Difference Notation:: + A similar notation 'r1\...r2' is called symmetric difference + of 'r1' and 'r2' and is defined as + 'r1 r2 --not $(git merge-base --all r1 r2)'. + It is the set of commits that are reachable from either one of + 'r1' (left side) or 'r2' (right side) but not from both. + +In these two shorthand notations, you can omit one end and let it default to HEAD. For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What did I do since I forked from the origin branch?" Similarly, '..origin' is a shorthand for 'HEAD..origin' and asks "What did the origin do since I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is an empty range that is both reachable and unreachable from HEAD. -Two other shorthands for naming a set that is formed by a commit -and its parent commits exist. The 'r1{caret}@' notation means all -parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes -all of its parents. +Other <rev>{caret} Parent Shorthand Notations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Two other shorthands exist, particularly useful for merge commits, +for naming a set that is formed by a commit and its parent commits. + +The 'r1{caret}@' notation means all parents of 'r1'. + +The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents. +By itself, this notation denotes the single commit 'r1'. + +While '<rev>{caret}<n>' was about specifying a single commit parent, these +two notations consider all its parents. For example you can say +'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'. -To summarize: +Revision Range Summary +---------------------- '<rev>':: - Include commits that are reachable from (i.e. ancestors of) - <rev>. + Include commits that are reachable from <rev> (i.e. <rev> and its + ancestors). '{caret}<rev>':: - Exclude commits that are reachable from (i.e. ancestors of) - <rev>. + Exclude commits that are reachable from <rev> (i.e. <rev> and its + ancestors). '<rev1>..<rev2>':: Include commits that are reachable from <rev2> but exclude @@ -300,16 +326,27 @@ To summarize: as giving commit '<rev>' and then all its parents prefixed with '{caret}' to exclude them (and their ancestors). -Here are a handful of examples: - - D G H D - D F G H I J D F - ^G D H D - ^D B E I J F B - B..C C - B...C G H D E B C - ^D B C E I J F B C - C I J F C - C^@ I J F - C^! C - F^! D G H D F +Here are a handful of examples using the Loeliger illustration above, +with each step in the notation's expansion and selection carefully +spelt out: + + Args Expanded arguments Selected commits + D G H D + D F G H I J D F + ^G D H D + ^D B E I J F B + ^D B C E I J F B C + C I J F C + B..C = ^B C C + B...C = B ^F C G H D E B C + C^@ = C^1 + = F I J F + B^@ = B^1 B^2 B^3 + = D E F D G H E F I J + C^! = C ^C^@ + = C ^C^1 + = C ^F C + B^! = B ^B^@ + = B ^B^1 ^B^2 ^B^3 + = B ^D ^E ^F B + F^! D = F ^I ^J D G H D F |