diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/CodingGuidelines | 8 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.7.11.5.txt | 36 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.7.11.6.txt | 62 | ||||
| -rw-r--r-- | Documentation/git-commit.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-daemon.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-describe.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-filter-branch.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-fsck.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-lost-found.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-merge.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-mergetool.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-pack-refs.txt | 19 | ||||
| -rw-r--r-- | Documentation/git-pull.txt | 1 | ||||
| -rw-r--r-- | Documentation/git-rebase.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-replace.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-tag.txt | 5 | ||||
| -rw-r--r-- | Documentation/git.txt | 3 | ||||
| -rw-r--r-- | Documentation/gitcli.txt | 8 | ||||
| -rw-r--r-- | Documentation/glossary-content.txt | 2 | ||||
| -rw-r--r-- | Documentation/rev-list-options.txt | 33 | ||||
| -rw-r--r-- | Documentation/revisions.txt | 43 | ||||
| -rw-r--r-- | Documentation/user-manual.txt | 12 |
22 files changed, 227 insertions, 44 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 45577117c2..57da6aadeb 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -76,11 +76,19 @@ For shell scripts specifically (not exhaustive): - We do not use Process Substitution <(list) or >(list). + - Do not write control structures on a single line with semicolon. + "then" should be on the next line for if statements, and "do" + should be on the next line for "while" and "for". + - We prefer "test" over "[ ... ]". - We do not write the noiseword "function" in front of shell functions. + - We prefer a space between the function name and the parentheses. The + opening "{" should also be on the same line. + E.g.: my_function () { + - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, [::], [==], nor [..]) for portability. diff --git a/Documentation/RelNotes/1.7.11.5.txt b/Documentation/RelNotes/1.7.11.5.txt new file mode 100644 index 0000000000..0a2ed855c5 --- /dev/null +++ b/Documentation/RelNotes/1.7.11.5.txt @@ -0,0 +1,36 @@ +Git v1.7.11.5 Release Notes +=========================== + +Fixes since v1.7.11.4 +--------------------- + + * The Makefile rule to create assembly output (primarily for + debugging purposes) did not create it next to the source. + + * The code to avoid mistaken attempt to add the object directory + itself as its own alternate could read beyond end of a string while + comparison. + + * On some architectures, "block-sha1" did not compile correctly + when compilers inferred alignment guarantees from our source we + did not intend to make. + + * When talking to a remote running ssh on IPv6 enabled host, whose + address is spelled as "[HOST]:PORT", we did not parse the address + correctly and failed to connect. + + * git-blame.el (in compat/) have been updated to use Elisp more + correctly. + + * "git checkout <branchname>" to come back from a detached HEAD state + incorrectly computed reachability of the detached HEAD, resulting + in unnecessary warnings. + + * "git mergetool" did not support --tool-help option to give the list + of supported backends, like "git difftool" does. + + * "git grep" stopped spawning an external "grep" long time ago, but a + duplicated test to check internal and external "grep" was left + behind. + +Also contains minor typofixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.11.6.txt b/Documentation/RelNotes/1.7.11.6.txt new file mode 100644 index 0000000000..84ba827b1b --- /dev/null +++ b/Documentation/RelNotes/1.7.11.6.txt @@ -0,0 +1,62 @@ +Git v1.7.11.6 Release Notes +=========================== + +Fixes since v1.7.11.5 +--------------------- + +This consists primarily of documentation updates and low-impact code +clarification and bugfixes. + + - "ciabot" script (in contrib/) has been updated with extensive + documentation. + + - The "--rebase" option to "git pull" can be abbreviated to "-r", + but we didn't document it. + + - It was generally understood that "--long-option"s to many of our + subcommands can be abbreviated to the unique prefix, but it was not + easy to find it described for new readers of the documentation set. + + - The "--topo-order", "--date-order" (and the lack of either means + the default order) options to "rev-list" and "log" family of + commands were poorly described in the documentation. + + - Older parts of the documentation described as if having a regular + file in .git/refs/ hierarchy were the only way to have branches and + tags, which is not true for quite some time. + + - A utility shell function test_seq has been added as a replacement + for the 'seq' utility found on some platforms. + + - Fallback 'getpass' implementation made unportable use of stdio API. + + - "git commit --amend" let the user edit the log message and then + died when the human-readable committer name was given + insufficiently by getpwent(3). + + - The reflog entries left by "git rebase" and "git rebase -i" were + inconsistent (the interactive one gave an abbreviated object name). + + - When the user exports a non-default IFS without HT, scripts that + rely on being able to parse "ls-files -s | while read a b c..." + started to fail. Protect them from such a misconfiguration. + + - When "git push" triggered the automatic gc on the receiving end, a + message from "git prune" that said it was removing cruft leaked to + the standard output, breaking the communication protocol. + + - "git diff" had a confusion between taking data from a path in the + working tree and taking data from an object that happens to have + name 0{40} recorded in a tree. + + - "git send-email" did not unquote encoded words that appear on the + header correctly, and lost "_" from strings. + + - When the user gives an argument that can be taken as both a + revision name and a pathname without disambiguating with "--", we + used to give a help message "Use '--' to separate". The message + has been clarified to show where that '--' goes on the command + line. + + - "gitweb" when used with PATH_INFO failed to notice directories with + SP (and other characters that need URL-style quoting) in them. diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 81853e9646..4622297ec9 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -101,12 +101,16 @@ OPTIONS When doing a dry-run, give the output in the short-format. See linkgit:git-status[1] for details. Implies `--dry-run`. +--branch:: + Show the branch and tracking info even in short-format. + --porcelain:: When doing a dry-run, give the output in a porcelain-ready format. See linkgit:git-status[1] for details. Implies `--dry-run`. -z:: +--null:: When showing `short` or `porcelain` status output, terminate entries in the status output with NUL, instead of LF. If no format is given, implies the `--porcelain` output format. @@ -189,6 +193,10 @@ OPTIONS current tip -- if it was a merge, it will have the parents of the current tip as parents -- so the current top commit is discarded. + +--no-post-rewrite:: + Bypass the post-rewrite hook. + + -- It is a rough equivalent for: diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 31b28fc29f..e8f757704c 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -204,7 +204,7 @@ receive-pack:: can push anything into the repository, including removal of refs). This is solely meant for a closed LAN setting where everybody is friendly. This service can be - enabled by `daemon.receivepack` configuration item to + enabled by setting `daemon.receivepack` configuration item to `true`. EXAMPLES diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 039cce2e98..72d6bb612b 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -36,12 +36,12 @@ OPTIONS --all:: Instead of using only the annotated tags, use any ref - found in `.git/refs/`. This option enables matching + found in `refs/` namespace. This option enables matching any known branch, remote-tracking branch, or lightweight tag. --tags:: Instead of using only the annotated tags, use any tag - found in `.git/refs/tags`. This option enables matching + found in `refs/tags` namespace. This option enables matching a lightweight (non-annotated) tag. --contains:: diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 81f58234a7..15e7ac80c0 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -32,7 +32,8 @@ changes, which would normally have no effect. Nevertheless, this may be useful in the future for compensating for some git bugs or such, therefore such a usage is permitted. -*NOTE*: This command honors `.git/info/grafts` and `.git/refs/replace/`. +*NOTE*: This command honors `.git/info/grafts` file and refs in +the `refs/replace/` namespace. If you have any grafts or replacement refs defined, running this command will make them permanent. diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index bbb25da2dd..da348fc942 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -23,8 +23,8 @@ OPTIONS An object to treat as the head of an unreachability trace. + If no objects are given, 'git fsck' defaults to using the -index file, all SHA1 references in .git/refs/*, and all reflogs (unless ---no-reflogs is given) as heads. +index file, all SHA1 references in `refs` namespace, and all reflogs +(unless --no-reflogs is given) as heads. --unreachable:: Print out objects that exist but that aren't reachable from any diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index c406a11001..d54932889f 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -48,7 +48,8 @@ $ gitk $(cd .git/lost-found/commit && echo ??*) ------------ After making sure you know which the object is the tag you are looking -for, you can reconnect it to your regular .git/refs hierarchy. +for, you can reconnect it to your regular `refs` hierarchy by using +the `update-ref` command. ------------ $ git cat-file -t 1ef2b196 diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 3ceefb8a1f..20f9228511 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -181,7 +181,7 @@ final result verbatim. When both sides made changes to the same area, however, git cannot randomly pick one side over the other, and asks you to resolve it by leaving what both sides did to that area. -By default, git uses the same style as that is used by "merge" program +By default, git uses the same style as the one used by the "merge" program from the RCS suite to present such a conflicted hunk, like this: ------------ diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 2a49de7cfe..d7207bd9b9 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -27,9 +27,9 @@ OPTIONS -t <tool>:: --tool=<tool>:: Use the merge resolution program specified by <tool>. - Valid merge tools are: - araxis, bc3, diffuse, ecmerge, emerge, gvimdiff, kdiff3, - meld, opendiff, p4merge, tkdiff, tortoisemerge, vimdiff and xxdiff. + Valid values include emerge, gvimdiff, kdiff3, + meld, vimdiff, and tortoisemerge. Run `git mergetool --tool-help` + for the list of valid <tool> settings. + If a merge resolution program is not specified, 'git mergetool' will use the configuration variable `merge.tool`. If the diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 10afd4edfe..f131677478 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -14,7 +14,8 @@ DESCRIPTION ----------- Traditionally, tips of branches and tags (collectively known as -'refs') were stored one file per ref under `$GIT_DIR/refs` +'refs') were stored one file per ref in a (sub)directory +under `$GIT_DIR/refs` directory. While many branch tips tend to be updated often, most tags and some branch tips are never updated. When a repository has hundreds or thousands of tags, this @@ -22,13 +23,14 @@ one-file-per-ref format both wastes storage and hurts performance. This command is used to solve the storage and performance -problem by stashing the refs in a single file, +problem by storing the refs in a single file, `$GIT_DIR/packed-refs`. When a ref is missing from the -traditional `$GIT_DIR/refs` hierarchy, it is looked up in this +traditional `$GIT_DIR/refs` directory hierarchy, it is looked +up in this file and used if found. Subsequent updates to branches always create new files under -`$GIT_DIR/refs` hierarchy. +`$GIT_DIR/refs` directory hierarchy. A recommended practice to deal with a repository with too many refs is to pack its refs with `--all --prune` once, and @@ -57,6 +59,15 @@ a repository with many branches of historical interests. The command usually removes loose refs under `$GIT_DIR/refs` hierarchy after packing them. This option tells it not to. + +BUGS +---- + +Older documentation written before the packed-refs mechanism was +introduced may still say things like ".git/refs/heads/<branch> file +exists" when it means "branch <branch> exists". + + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index defb544ed0..67fa5ee195 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -101,6 +101,7 @@ include::merge-options.txt[] :git-pull: 1 +-r:: --rebase:: Rebase the current branch on top of the upstream branch after fetching. If there is a remote-tracking branch corresponding to diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 147fa1a8e0..feb51a6ea3 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -273,7 +273,7 @@ which makes little sense. Pass the <strategy-option> through to the merge strategy. This implies `--merge` and, if no strategy has been specified, `-s recursive`. Note the reversal of 'ours' and - 'theirs' as noted in above for the `-m` option. + 'theirs' as noted above for the `-m` option. -q:: --quiet:: diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 17df525275..51131d0858 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -14,14 +14,13 @@ SYNOPSIS DESCRIPTION ----------- -Adds a 'replace' reference in `.git/refs/replace/` +Adds a 'replace' reference in `refs/replace/` namespace. The name of the 'replace' reference is the SHA1 of the object that is replaced. The content of the 'replace' reference is the SHA1 of the replacement object. -Unless `-f` is given, the 'replace' reference must not yet exist in -`.git/refs/replace/` directory. +Unless `-f` is given, the 'replace' reference must not yet exist. Replacement references will be used by default by all git commands except those doing reachability traversal (prune, pack transfer and diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index e36a7c3d1e..247534e908 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -20,11 +20,10 @@ SYNOPSIS DESCRIPTION ----------- -Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given +Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given to delete, list or verify tags. -Unless `-f` is given, the tag to be created must not yet exist in the -`.git/refs/tags/` directory. +Unless `-f` is given, the named tag must not yet exist. If one of `-a`, `-s`, or `-u <key-id>` is passed, the command creates a 'tag' object, and requires a tag message. Unless diff --git a/Documentation/git.txt b/Documentation/git.txt index 7af8aaa047..677eb95995 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -44,9 +44,10 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.7.11.4/git.html[documentation for release 1.7.11.4] +* link:v1.7.11.5/git.html[documentation for release 1.7.11.5] * release notes for + link:RelNotes/1.7.11.5.txt[1.7.11.5], link:RelNotes/1.7.11.4.txt[1.7.11.4], link:RelNotes/1.7.11.3.txt[1.7.11.3], link:RelNotes/1.7.11.2.txt[1.7.11.2], diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index ea17f7a53b..3e72a5d68e 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -62,6 +62,14 @@ scripting git: `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work if you happen to have a file called `HEAD` in the work tree. + * many commands allow a long option "--option" to be abbreviated + only to their unique prefix (e.g. if there is no other option + whose name begins with "opt", you may be able to spell "--opt" to + invoke the "--option" flag), but you should fully spell them out + when writing your scripts; later versions of Git may introduce a + new option whose name shares the same prefix, e.g. "--optimize", + to make a short prefix that used to be unique no longer unique. + ENHANCED OPTION PARSER ---------------------- diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 3595b586bc..f928b57f90 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -117,7 +117,7 @@ to point at the new commit. [[def_ent]]ent:: Favorite synonym to "<<def_tree-ish,tree-ish>>" by some total geeks. See - `http://en.wikipedia.org/wiki/Ent_(Middle-earth)` for an in-depth + http://en.wikipedia.org/wiki/Ent_(Middle-earth) for an in-depth explanation. Avoid this term, not to confuse people. [[def_evil_merge]]evil merge:: diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 84e34b1aba..def1340ac7 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -578,16 +578,33 @@ Commit Ordering By default, the commits are shown in reverse chronological order. ---topo-order:: +--date-order:: + Show no parents before all of its children are shown, but + otherwise show commits in the commit timestamp order. - This option makes them appear in topological order (i.e. - descendant commits are shown before their parents). +--topo-order:: + Show no parents before all of its children are shown, and + avoid showing commits on multiple lines of history + intermixed. ++ +For example, in a commit history like this: ++ +---------------------------------------------------------------- ---date-order:: + ---1----2----4----7 + \ \ + 3----5----6----8--- - This option is similar to '--topo-order' in the sense that no - parent comes before all of its children, but otherwise things - are still ordered in the commit timestamp order. +---------------------------------------------------------------- ++ +where the numbers denote the order of commit timestamps, `git +rev-list` and friends with `--date-order` show the commits in the +timestamp order: 8 7 6 5 4 3 2 1. ++ +With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5 +3 1); some older commits are shown before newer ones in order to +avoid showing the commits from two parallel development track mixed +together. --reverse:: @@ -760,7 +777,7 @@ options may be given. See linkgit:git-diff-files[1] for more options. --cc:: - This flag implies the '-c' options and further compresses the + This flag implies the '-c' option and further compresses the patch output by omitting uninteresting hunks whose contents in the parents have only two variants and the merge result picks one of them without modification. diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 1725661837..dc0070bcb7 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -24,22 +24,22 @@ blobs contained in a commit. object referenced by 'refs/heads/master'. If you happen to have both 'heads/master' and 'tags/master', you can explicitly say 'heads/master' to tell git which one you mean. - When ambiguous, a '<name>' is disambiguated by taking the + When ambiguous, a '<refname>' is disambiguated by taking the first match in the following rules: - . If '$GIT_DIR/<name>' exists, that is what you mean (this is usually + . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD' and 'CHERRY_PICK_HEAD'); - . otherwise, 'refs/<name>' if it exists; + . otherwise, 'refs/<refname>' if it exists; . otherwise, 'refs/tags/<refname>' if it exists; - . otherwise, 'refs/heads/<name>' if it exists; + . otherwise, 'refs/heads/<refname>' if it exists; - . otherwise, 'refs/remotes/<name>' if it exists; + . otherwise, 'refs/remotes/<refname>' if it exists; - . otherwise, 'refs/remotes/<name>/HEAD' if it exists. + . otherwise, 'refs/remotes/<refname>/HEAD' if it exists. + 'HEAD' names the commit on which you based the changes in the working tree. 'FETCH_HEAD' records the branch which you fetched from a remote repository @@ -218,13 +218,44 @@ 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. +To summarize: + +'<rev>':: + Include commits that are reachable from (i.e. ancestors of) + <rev>. + +'{caret}<rev>':: + Exclude commits that are reachable from (i.e. ancestors of) + <rev>. + +'<rev1>..<rev2>':: + Include commits that are reachable from <rev2> but exclude + those that are reachable from <rev1>. + +'<rev1>\...<rev2>':: + Include commits that are reachable from either <rev1> or + <rev2> but exclude those that are reachable from both. + +'<rev>{caret}@', e.g. 'HEAD{caret}@':: + A suffix '{caret}' followed by an at sign is the same as listing + all parents of '<rev>' (meaning, include anything reachable from + its parents, but not the commit itself). + +'<rev>{caret}!', e.g. 'HEAD{caret}!':: + A suffix '{caret}' followed by an exclamation mark is the same + 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 diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 02ed5668e1..03d95dc290 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -2870,7 +2870,7 @@ $ git fetch example You can also add a "+" to force the update each time: ------------------------------------------------- -$ git config remote.example.fetch +master:ref/remotes/example/master +$ git config remote.example.fetch +master:refs/remotes/example/master ------------------------------------------------- Don't do this unless you're sure you won't mind "git fetch" possibly @@ -2966,7 +2966,7 @@ As you can see, a commit is defined by: - a tree: The SHA-1 name of a tree object (as defined below), representing the contents of a directory at a certain point in time. -- parent(s): The SHA-1 name of some number of commits which represent the +- parent(s): The SHA-1 name(s) of some number of commits which represent the immediately previous step(s) in the history of the project. The example above has one parent; merge commits may have more than one. A commit with no parents is called a "root" commit, and @@ -3363,8 +3363,8 @@ Date: :100644 100644 oldsha... 4b9458b... M somedirectory/myfile ------------------------------------------------ -This tells you that the immediately preceding version of the file was -"newsha", and that the immediately following version was "oldsha". +This tells you that the immediately following version of the file was +"newsha", and that the immediately preceding version was "oldsha". You also know the commit messages that went with the change from oldsha to 4b9458b and with the change from 4b9458b to newsha. @@ -4035,8 +4035,8 @@ $ git ls-files --unmerged Each line of the `git ls-files --unmerged` output begins with the blob mode bits, blob SHA-1, 'stage number', and the filename. The 'stage number' is git's way to say which tree it -came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD` -tree, and stage3 `$target` tree. +came from: stage 1 corresponds to the `$orig` tree, stage 2 to +the `HEAD` tree, and stage 3 to the `$target` tree. Earlier we said that trivial merges are done inside `git read-tree -m`. For example, if the file did not change |