diff options
Diffstat (limited to 'Documentation')
40 files changed, 511 insertions, 116 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/Makefile b/Documentation/Makefile index 063fa696c9..cf5916fe8b 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -344,4 +344,7 @@ require-htmlrepo:: quick-install-html: require-htmlrepo '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) +print-man1: + @for i in $(MAN1_TXT); do echo $$i; done + .PHONY: FORCE diff --git a/Documentation/RelNotes/1.7.11.6.txt b/Documentation/RelNotes/1.7.11.6.txt new file mode 100644 index 0000000000..ba7d3c3966 --- /dev/null +++ b/Documentation/RelNotes/1.7.11.6.txt @@ -0,0 +1,84 @@ +Git v1.7.11.6 Release Notes +=========================== + +Fixes since v1.7.11.5 +--------------------- + + * "ciabot" script (in contrib/) has been updated with extensive + documentation. + + * "git foo" errored out with "Not a directory" when the user had a + non-directory on $PATH, and worse yet it masked an alias "foo" from + running. + + * 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 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. + + * Documentation for the configuration file format had a confusing + example. + + * 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. + + * 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. + + * "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 exit status code from "git config" was way overspecified while + being incorrect. The implementation has been updated to give the + documented status for a case that was documented, and introduce a + new code for "all other errors". + + * The output from "git diff -B" for a file that ends with an + incomplete line did not put "\ No newline..." on a line of its own. + + * "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. + + * The "--rebase" option to "git pull" can be abbreviated to "-r", + but we didn't document it. + + * 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. + + * The reflog entries left by "git rebase" and "git rebase -i" were + inconsistent (the interactive one gave an abbreviated object name). + + * "git send-email" did not unquote encoded words that appear on the + header correctly, and lost "_" from strings. + + * "git stash apply/pop" did not trigger "rerere" upon conflicts + unlike other mergy operations. + + * "git submodule <cmd> path" did not error out when the path to the + submodule was misspelt. + + * "git submodule update -f" did not update paths in the working tree + that has local changes. + (merge 01d4721 sz/submodule-force-update later to maint). + + * "gitweb" when used with PATH_INFO failed to notice directories with + SP (and other characters that need URL-style quoting) in them. + + * Fallback 'getpass' implementation made unportable use of stdio API. + + * A utility shell function test_seq has been added as a replacement + for the 'seq' utility found on some platforms. diff --git a/Documentation/RelNotes/1.7.11.7.txt b/Documentation/RelNotes/1.7.11.7.txt new file mode 100644 index 0000000000..e7e79d999b --- /dev/null +++ b/Documentation/RelNotes/1.7.11.7.txt @@ -0,0 +1,46 @@ +Git v1.7.11.7 Release Notes +=========================== + +Fixes since v1.7.11.6 +--------------------- + + * The synopsis said "checkout [-B branch]" to make it clear the + branch name is a parameter to the option, but the heading for the + option description was "-B::", not "-B branch::", making the + documentation misleading. + + * Git ships with a fall-back regexp implementation for platforms with + buggy regexp library, but it was easy for people to keep using their + platform regexp. A new test has been added to check this. + + * "git apply -p0" did not parse pathnames on "diff --git" line + correctly. This caused patches that had pathnames in no other + places to be mistakenly rejected (most notably, binary patch that + does not rename nor change mode). Textual patches, renames or mode + changes have preimage and postimage pathnames in different places + in a form that can be parsed unambiguously and did not suffer from + this problem. + + * After "gitk" showed the contents of a tag, neither "Reread + references" nor "Reload" did not update what is shown as the + contents of it, when the user overwrote the tag with "git tag -f". + + * "git for-each-ref" did not currectly support more than one --sort + option. + + * "git log .." errored out saying it is both rev range and a path + when there is no disambiguating "--" is on the command line. + Update the command line parser to interpret ".." as a path in such + a case. + + * Pushing to smart HTTP server with recent Git fails without having + the username in the URL to force authentication, if the server is + configured to allow GET anonymously, while requiring authentication + for POST. + + * "git show --format='%ci'" did not give timestamp correctly for + commits created without human readable name on "committer" line. + (merge e27ddb6 jc/maint-ident-missing-human-name later to maint). + + * "git show --quiet" ought to be a synonym for "git show -s", but + wasn't. diff --git a/Documentation/RelNotes/1.7.12.1.txt b/Documentation/RelNotes/1.7.12.1.txt new file mode 100644 index 0000000000..b8f04af19f --- /dev/null +++ b/Documentation/RelNotes/1.7.12.1.txt @@ -0,0 +1,134 @@ +Git 1.7.12.1 Release Notes +========================== + +Fixes since v1.7.12 +------------------- + + * "git apply -p0" did not parse pathnames on "diff --git" line + correctly. This caused patches that had pathnames in no other + places to be mistakenly rejected (most notably, binary patch that + does not rename nor change mode). Textual patches, renames or mode + changes have preimage and postimage pathnames in different places + in a form that can be parsed unambiguously and did not suffer from + this problem. + + * "git cherry-pick A C B" used to replay changes in A and then B and + then C if these three commits had committer timestamps in that + order, which is not what the user who said "A C B" naturally + expects. + + * "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). + + * Some capabilities were asked by fetch-pack even when upload-pack + did not advertise that they are available. fetch-pack has been + fixed not to do so. + + * "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 for-each-ref" did not correctly support more than one --sort + option. + + * "git log .." errored out saying it is both rev range and a path + when there is no disambiguating "--" is on the command line. + Update the command line parser to interpret ".." as a path in such + a case. + + * 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. + + * "git prune" without "-v" used to warn about leftover temporary + files (which is an indication of an earlier aborted operation). + + * Pushing to smart HTTP server with recent Git fails without having + the username in the URL to force authentication, if the server is + configured to allow GET anonymously, while requiring authentication + for POST. + + * The reflog entries left by "git rebase" and "git rebase -i" were + inconsistent (the interactive one gave an abbreviated object name). + + * 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 show --quiet" ought to be a synonym for "git show -s", but + wasn't. + + * "git show --format='%ci'" did not give timestamp correctly for + commits created without human readable name on "committer" line. + + * "git send-email" did not unquote encoded words that appear on the + header correctly, and lost "_" from strings. + + * The interactive prompt "git send-email" gives was error prone. It + asked "What e-mail address do you want to use?" with the address it + guessed (correctly) the user would want to use in its prompt, + tempting the user to say "y". But the response was taken as "No, + please use 'y' as the e-mail address instead", which is most + certainly not what the user meant. + + * "gitweb" when used with PATH_INFO failed to notice directories with + SP (and other characters that need URL-style quoting) in them. + + * 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. + + * 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. + + * The attribute system may be asked for a path that itself or its + leading directories no longer exists in the working tree, and it is + fine if we cannot open .gitattribute file in such a case. Failure + to open per-directory .gitattributes with error status other than + ENOENT and ENOTDIR should be diagnosed, but it wasn't. + + * After "gitk" showed the contents of a tag, neither "Reread + references" nor "Reload" did not update what is shown as the + contents of it, when the user overwrote the tag with "git tag -f". + + * "ciabot" script (in contrib/) has been updated with extensive + documentation. + + * "git-jump" script (in contrib/) did not work well when + diff.noprefix or diff.mnemonicprefix is in effect. + + * 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. + + * Compatibility wrapper to learn the maximum number of file + descriptors we can open around sysconf(_SC_OPEN_MAX) and + getrlimit(RLIMIT_NO_FILE) has been introduced for portability. + + * We used curl_easy_strerror() without checking version of cURL, + breaking the build for versions before curl 7.12.0. + + * Code to work around MacOS X UTF-8 gotcha has been cleaned up. + + * Fallback 'getpass' implementation made unportable use of stdio API. + + * 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 synopsis said "checkout [-B branch]" to make it clear the + branch name is a parameter to the option, but the heading for the + option description was "-B::", not "-B branch::", making the + documentation misleading. + +Also contains numerous documentation updates. diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index a26d245ab4..1273a85c8a 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -36,7 +36,7 @@ ifndef::git-asciidoc-no-roff[] # v1.72 breaks with this because it replaces dots not in roff requests. [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> ifdef::doctype-manpage[] .ft C endif::doctype-manpage[] @@ -53,7 +53,7 @@ ifdef::doctype-manpage[] # The following two small workarounds insert a simple paragraph after screen [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> | </literallayout><simpara></simpara> {title#}</example> diff --git a/Documentation/config.txt b/Documentation/config.txt index a95e5a4ac9..122e3c4996 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -559,8 +559,9 @@ core.whitespace:: * `space-before-tab` treats a space character that appears immediately before a tab character in the initial indent part of the line as an error (enabled by default). -* `indent-with-non-tab` treats a line that is indented with 8 or more - space characters as an error (not enabled by default). +* `indent-with-non-tab` treats a line that is indented with space + characters instead of the equivalent tabs as an error (not enabled by + default). * `tab-in-indent` treats a tab character in the initial indent part of the line as an error (not enabled by default). * `blank-at-eof` treats blank lines added at the end of file as an error diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 63a251612a..7958a47006 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -84,11 +84,11 @@ entries; instead, unmerged entries are ignored. When checking out paths from the index, check out stage #2 ('ours') or #3 ('theirs') for unmerged paths. --b:: +-b <new_branch>:: Create a new branch named <new_branch> and start it at <start_point>; see linkgit:git-branch[1] for details. --B:: +-B <new_branch>:: Creates the branch <new_branch> and start it at <start_point>; if it already exists, then reset it to <start_point>. This is equivalent to running "git branch" with "-f"; see @@ -124,7 +124,7 @@ explicitly give a name with '-b' in such a case. <commit> is not a branch name. See the "DETACHED HEAD" section below for details. ---orphan:: +--orphan <new_branch>:: Create a new 'orphan' branch, named <new_branch>, started from <start_point> and switch to it. The first commit made on this new branch will have no parents and it will be the root of a new @@ -367,6 +367,18 @@ $ git checkout hello.c <3> <2> take a file out of another commit <3> restore hello.c from the index + +If you want to check out _all_ C source files out of the index, +you can say ++ +------------ +$ git checkout -- '*.c' +------------ ++ +Note the quotes around `*.c`. The file `hello.c` will also be +checked out, even though it is no longer in the working tree, +because the file globbing is used to match entries in the index +(not in the working tree by the shell). ++ If you have an unfortunate branch that is named `hello.c`, this step would be confused as an instruction to switch to that branch. You should instead write: diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 4622297ec9..9594ac8e9d 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -389,8 +389,10 @@ DISCUSSION Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. -Tools that turn commits into email, for example, use the first line -on the Subject: line and the rest of the commit in the body. +The text up to the first blank line in a commit message is treated +as the commit title, and that title is used throughout git. +For example, linkgit:git-format-patch[1] turns a commit into email, and it uses +the title on the Subject line and the rest of the commit in the body. include::i18n.txt[] diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 2d6ef32a08..eaea079165 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -54,16 +54,16 @@ configuration file by default, and options '--system', '--global', '--file <filename>' can be used to tell the command to write to that location (you can say '--local' but that is the default). -This command will fail (with exit code ret) if: +This command will fail with non-zero status upon error. Some exit +codes are: . The config file is invalid (ret=3), . can not write to the config file (ret=4), . no section or name was provided (ret=2), . the section or key is invalid (ret=1), . you try to unset an option which does not exist (ret=5), -. you try to unset/set an option for which multiple lines match (ret=5), -. you try to use an invalid regexp (ret=6), or -. you use '--global' option without $HOME being properly set (ret=128). +. you try to unset/set an option for which multiple lines match (ret=5), or +. you try to use an invalid regexp (ret=6). On success, the command returns the exit code 0. @@ -267,7 +267,7 @@ Given a .git/config like this: ; Proxy settings [core] - gitproxy="proxy-command" for kernel.org + gitproxy=proxy-command for kernel.org gitproxy=default-proxy ; for all the rest you can set the filemode to true with @@ -342,7 +342,7 @@ To actually match only values with an exclamation mark, you have to To add a new proxy, without altering any of the existing ones, use ------------ -% git config core.gitproxy '"proxy-command" for example.com' +% git config --add core.gitproxy '"proxy-command" for example.com' ------------ An example to use customized color from the configuration in your diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt index 11edc5a173..d15db42d43 100644 --- a/Documentation/git-credential-cache--daemon.txt +++ b/Documentation/git-credential-cache--daemon.txt @@ -3,7 +3,7 @@ git-credential-cache--daemon(1) NAME ---- -git-credential-cache--daemon - temporarily store user credentials in memory +git-credential-cache--daemon - Temporarily store user credentials in memory SYNOPSIS -------- diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt index f3d09c5d51..eeff5fa989 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -3,7 +3,7 @@ git-credential-cache(1) NAME ---- -git-credential-cache - helper to temporarily store passwords in memory +git-credential-cache - Helper to temporarily store passwords in memory SYNOPSIS -------- diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index 31093467d1..b27c03c361 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -3,7 +3,7 @@ git-credential-store(1) NAME ---- -git-credential-store - helper to store credentials on disk +git-credential-store - Helper to store credentials on disk SYNOPSIS -------- 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-fast-import.txt b/Documentation/git-fast-import.txt index 2620d28b4b..6603a7ab73 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -39,6 +39,10 @@ OPTIONS See ``Date Formats'' below for details about which formats are supported, and their syntax. +-- done:: + Terminate with error if there is no 'done' command at the + end of the stream. + --force:: Force updating modified existing branches, even if doing so would cause commits to be lost (as the new commit does @@ -1047,7 +1051,9 @@ done:: Error out if the stream ends without a 'done' command. Without this feature, errors causing the frontend to end abruptly at a convenient point in the stream can go - undetected. + undetected. This may occur, for example, if an import + front end dies in mid-operation without emitting SIGTERM + or SIGKILL at its subordinate git fast-import instance. `option` ~~~~~~~~ diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 81f58234a7..e2301f5c01 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. @@ -303,6 +304,11 @@ committed a merge between P1 and P2, it will be propagated properly and all children of the merge will become merge commits with P1,P2 as their parents instead of the merge commit. +*NOTE* the changes introduced by the commits, and which are not reverted +by subsequent commits, will still be in the rewritten branch. If you want +to throw out _changes_ together with the commits, you should use the +interactive mode of 'git rebase'. + You can rewrite the commit log messages using `--msg-filter`. For example, 'git svn-id' strings in a repository created by 'git svn' can be removed this way: @@ -313,11 +319,6 @@ git filter-branch --msg-filter ' ' ------------------------------------------------------- -To restrict rewriting to only part of the history, specify a revision -range in addition to the new branch name. The new branch name will -point to the top-most revision that a 'git rev-list' of this range -will print. - If you need to add 'Acked-by' lines to, say, the last 10 commits (none of which is a merge), use this command: @@ -328,11 +329,10 @@ git filter-branch --msg-filter ' ' HEAD~10..HEAD -------------------------------------------------------- -*NOTE* the changes introduced by the commits, and which are not reverted -by subsequent commits, will still be in the rewritten branch. If you want -to throw out _changes_ together with the commits, you should use the -interactive mode of 'git rebase'. - +To restrict rewriting to only part of the history, specify a revision +range in addition to the new branch name. The new branch name will +point to the top-most revision that a 'git rev-list' of this range +will print. Consider this history: diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index c872b883ba..db55a4e0bb 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -102,9 +102,10 @@ Fields that have name-email-date tuple as its value (`author`, and `date` to extract the named component. The complete message in a commit and tag object is `contents`. -Its first line is `contents:subject`, the remaining lines -are `contents:body` and the optional GPG signature -is `contents:signature`. +Its first line is `contents:subject`, where subject is the concatenation +of all lines of the commit message up to the first blank line. The next +line is 'contents:body', where body is all of the lines after the first +blank line. Finally, the optional GPG signature is `contents:signature`. For sorting purposes, fields with numeric values sort in numeric order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 04c7346e3e..6d43f56279 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -58,10 +58,13 @@ output, unless the `--stdout` option is specified. If `-o` is specified, output files are created in <dir>. Otherwise they are created in the current working directory. -By default, the subject of a single patch is "[PATCH] First Line" and -the subject when multiple patches are output is "[PATCH n/m] First -Line". To force 1/1 to be added for a single patch, use `-n`. To omit -patch numbers from the subject, use `-N`. +By default, the subject of a single patch is "[PATCH] " followed by +the concatenation of lines from the commit message up to the first blank +line (see the DISCUSSION section of linkgit:git-commit[1]). + +When multiple patches are output, the subject prefix will instead be +"[PATCH n/m] ". To force 1/1 to be added for a single patch, use `-n`. +To omit patch numbers from the subject, use `-N`. If given `--thread`, `git-format-patch` will generate `In-Reply-To` and `References` headers to make the second and subsequent patch mails appear 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-log.txt b/Documentation/git-log.txt index 1f906208f9..585dac40ba 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -24,10 +24,6 @@ each commit introduces are shown. OPTIONS ------- --<n>:: - Limits the number of commits to show. - Note that this is a commit limiting option, see below. - <since>..<until>:: Show only commits between the named two commits. When either <since> or <until> is omitted, it defaults to @@ -137,6 +133,8 @@ Examples This makes sense only when following a strict policy of merging all topic branches when staying on a single integration branch. +`git log -3`:: + Limits the number of commits to show to 3. Discussion ---------- 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-ls-remote.txt b/Documentation/git-ls-remote.txt index 7a9b86a58a..774de5e9d9 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -42,6 +42,11 @@ OPTIONS it successfully talked with the remote repository, whether it found any matching refs. +--get-url:: + Expand the URL of the given remote repository taking into account any + "url.<base>.insteadOf" config setting (See linkgit:git-config[1]) and + exit without talking to the remote. + <repository>:: Location of the repository. The shorthand defined in $GIT_DIR/branches/ can be used. Use "." (dot) to list references in 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-remote.txt b/Documentation/git-remote.txt index a308f4c79f..e8c396b5f9 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git remote' [-v | --verbose] 'git remote add' [-t <branch>] [-m <master>] [-f] [--tags|--no-tags] [--mirror=<fetch|push>] <name> <url> 'git remote rename' <old> <new> -'git remote rm' <name> +'git remote remove' <name> 'git remote set-head' <name> (-a | -d | <branch>) 'git remote set-branches' [--add] <name> <branch>... 'git remote set-url' [--push] <name> <newurl> [<oldurl>] @@ -85,6 +85,7 @@ In case <old> and <new> are the same, and <old> is a file under `$GIT_DIR/remotes` or `$GIT_DIR/branches`, the remote is converted to the configuration file format. +'remove':: 'rm':: Remove the remote named <name>. All remote-tracking branches and 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-shortlog.txt b/Documentation/git-shortlog.txt index 01d8417316..afeb4cdf16 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -14,8 +14,7 @@ git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w] DESCRIPTION ----------- Summarizes 'git log' output in a format suitable for inclusion -in release announcements. Each commit will be grouped by author and -the first line of the commit message will be shown. +in release announcements. Each commit will be grouped by author and title. Additionally, "[PATCH]" will be stripped from the commit description. diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index fbbbcb282c..2de7bf0900 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -149,6 +149,11 @@ submodule with the `--init` option. + If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. ++ +If `--force` is specified, the submodule will be checked out (using +`git checkout --force` if appropriate), even if the commit specified in the +index of the containing repository already matches the commit checked out in +the submodule. summary:: Show commit summary between the given commit (defaults to HEAD) and @@ -210,7 +215,9 @@ OPTIONS This option is only valid for add and update commands. When running add, allow adding an otherwise ignored submodule path. When running update, throw away local changes in submodules when - switching to a different commit. + switching to a different commit; and always run a checkout operation + in the submodule, even if the commit listed in the index of the + containing repository matches the commit checked out in the submodule. --cached:: This option is only valid for status and summary commands. These 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 27da0eb209..6710cb0a41 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -22,18 +22,17 @@ unusually rich command set that provides both high-level operations and full access to internals. See linkgit:gittutorial[7] to get started, then see -link:everyday.html[Everyday Git] for a useful minimum set of commands, and -"man git-commandname" for documentation of each command. CVS users may -also want to read linkgit:gitcvs-migration[7]. See -the link:user-manual.html[Git User's Manual] for a more in-depth -introduction. +link:everyday.html[Everyday Git] for a useful minimum set of +commands. The link:user-manual.html[Git User's Manual] has a more +in-depth introduction. -The '<command>' is either a name of a Git command (see below) or an alias -as defined in the configuration file (see linkgit:git-config[1]). +After you mastered the basic concepts, you can come back to this +page to learn what commands git offers. You can learn more about +individual git commands with "git help command". linkgit:gitcli[7] +manual page gives you an overview of the command line command syntax. -Formatted and hyperlinked version of the latest git -documentation can be viewed at -`http://git-htmldocs.googlecode.com/git/git.html`. +Formatted and hyperlinked version of the latest git documentation +can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`. ifdef::stalenotes[] [NOTE] @@ -44,14 +43,17 @@ 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.12/git.html[documentation for release 1.7.12] +* link:v1.7.12.1/git.html[documentation for release 1.7.12.1] * release notes for + link:RelNotes/1.7.12.1.txt[1.7.12.1], link:RelNotes/1.7.12.txt[1.7.12]. -* link:v1.7.11.5/git.html[documentation for release 1.7.11.5] +* link:v1.7.11.7/git.html[documentation for release 1.7.11.7] * release notes for + link:RelNotes/1.7.11.7.txt[1.7.11.7], + link:RelNotes/1.7.11.6.txt[1.7.11.6], 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], @@ -411,24 +413,6 @@ help ...`. linkgit:git-replace[1] for more information. -FURTHER DOCUMENTATION ---------------------- - -See the references above to get started using git. The following is -probably more detail than necessary for a first-time user. - -The link:user-manual.html#git-concepts[git concepts chapter of the -user-manual] and linkgit:gitcore-tutorial[7] both provide -introductions to the underlying git architecture. - -See linkgit:gitworkflows[7] for an overview of recommended workflows. - -See also the link:howto-index.html[howto] documents for some useful -examples. - -The internals are documented in the -link:technical/api-index.html[GIT API documentation]. - GIT COMMANDS ------------ @@ -848,6 +832,29 @@ The index is also capable of storing multiple entries (called "stages") for a given pathname. These stages are used to hold the various unmerged version of a file when a merge is in progress. +FURTHER DOCUMENTATION +--------------------- + +See the references in the "description" section to get started +using git. The following is probably more detail than necessary +for a first-time user. + +The link:user-manual.html#git-concepts[git concepts chapter of the +user-manual] and linkgit:gitcore-tutorial[7] both provide +introductions to the underlying git architecture. + +See linkgit:gitworkflows[7] for an overview of recommended workflows. + +See also the link:howto-index.html[howto] documents for some useful +examples. + +The internals are documented in the +link:technical/api-index.html[GIT API documentation]. + +Users migrating from CVS may also want to +read linkgit:gitcvs-migration[7]. + + Authors ------- Git was started by Linus Torvalds, and is currently maintained by Junio diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index ea17f7a53b..f6ba90c2da 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -37,11 +37,28 @@ arguments. Here are the rules: file called HEAD in your work tree, `git diff HEAD` is ambiguous, and you have to say either `git diff HEAD --` or `git diff -- HEAD` to disambiguate. - ++ When writing a script that is expected to handle random user-input, it is a good practice to make it explicit which arguments are which by placing disambiguating `--` at appropriate places. + * Many commands allow wildcards in paths, but you need to protect + them from getting globbed by the shell. These two mean different + things: ++ +-------------------------------- +$ git checkout -- *.c +$ git checkout -- \*.c +-------------------------------- ++ +The former lets your shell expand the fileglob, and you are asking +the dot-C files in your working tree to be overwritten with the version +in the index. The latter passes the `*.c` to Git, and you are asking +the paths in the index that match the pattern to be checked out to your +working tree. After running `git add hello.c; rm hello.c`, you will _not_ +see `hello.c` in your working tree with the former, but with the latter +you will. + Here are the rules regarding the "flags" that you should follow when you are scripting git: @@ -62,6 +79,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/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 9d893369a0..5325c5a7d5 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -956,12 +956,11 @@ $ git show-branch --topo-order --more=1 master mybranch ------------------------------------------------ The first two lines indicate that it is showing the two branches -and the first line of the commit log message from their -top-of-the-tree commits, you are currently on `master` branch -(notice the asterisk `*` character), and the first column for -the later output lines is used to show commits contained in the +with the titles of their top-of-the-tree commits, you are currently on +`master` branch (notice the asterisk `*` character), and the first +column for the later output lines is used to show commits contained in the `master` branch, and the second column for the `mybranch` -branch. Three commits are shown along with their log messages. +branch. Three commits are shown along with their titles. All of them have non blank characters in the first column (`*` shows an ordinary commit on the current branch, `-` is a merge commit), which means they are now part of the `master` branch. Only the "Some diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index dee050567e..f1cb6f3be6 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -139,9 +139,11 @@ them to the index, and commit, all in one step. A note on commit messages: Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more -thorough description. Tools that turn commits into email, for -example, use the first line on the Subject: line and the rest of the -commit in the body. +thorough description. The text up to the first blank line in a commit +message is treated as the commit title, and that title is used +throughout git. For example, linkgit:git-format-patch[1] turns a +commit into email, and it uses the title on the Subject line and the +rest of the commit in the body. Git tracks content not files ---------------------------- diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index e3d8a83b23..d9eddedc72 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -130,6 +130,9 @@ The placeholders are: - '%b': body - '%B': raw body (unwrapped subject and body) - '%N': commit notes +- '%GG': raw verification message from GPG for a signed commit +- '%G?': show either "G" for Good or "B" for Bad for a signed commit +- '%GS': show the name of the signer for a signed commit - '%gD': reflog selector, e.g., `refs/stash@{1}` - '%gd': shortened reflog selector, e.g., `stash@{1}` - '%gn': reflog identity name diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 2a3dc8664f..5e499421a4 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -66,3 +66,7 @@ being displayed. Examples: "--notes=foo" will show only notes from --[no-]standard-notes:: These options are deprecated. Use the above --notes/--no-notes options instead. + +--show-signature:: + Check the validity of a signed commit object by passing the signature + to `gpg --verify` and show the output. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index d9b2b5b2e0..918c1109f2 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -8,7 +8,8 @@ ordering and formatting options, such as '--reverse'. -- --n 'number':: +-<number>:: +-n <number>:: --max-count=<number>:: Limit the number of commits to output. @@ -578,16 +579,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:: @@ -619,10 +637,14 @@ These options are mostly targeted for packing of git repositories. Only useful with '--objects'; print the object IDs that are not in packs. ---no-walk:: +--no-walk[=(sorted|unsorted)]:: - Only show the given revs, but do not traverse their ancestors. - This has no effect if a range is specified. + Only show the given commits, but do not traverse their ancestors. + This has no effect if a range is specified. If the argument + "unsorted" is given, the commits are show in the order they were + given on the command line. Otherwise (if "sorted" or no argument + was given), the commits are show in reverse chronological order + by commit time. --do-walk:: diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index dc0070bcb7..69d996bc38 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -213,6 +213,13 @@ of 'r1' and 'r2' and is defined as 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. +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 diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 49cdc571cd..d51e20f352 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -259,8 +259,10 @@ a positive depth, this step is skipped. ---- If the client has requested a positive depth, the server will compute -the set of commits which are no deeper than the desired depth, starting -at the client's wants. The server writes 'shallow' lines for each +the set of commits which are no deeper than the desired depth. The set +of commits start at the client's wants. + +The server writes 'shallow' lines for each commit whose parents will not be sent as a result. The server writes an 'unshallow' line for each commit which the client has indicated is shallow, but is no longer shallow at the currently requested depth diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf index 339b30919e..d87294de2f 100644 --- a/Documentation/user-manual.conf +++ b/Documentation/user-manual.conf @@ -14,7 +14,7 @@ ifdef::backend-docbook[] # "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. [listingblock] <example><title>{title}</title> -<literallayout> +<literallayout class="monospaced"> | </literallayout> {title#}</example> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 03d95dc290..85651b57ae 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1136,9 +1136,12 @@ Creating good commit messages Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough -description. Tools that turn commits into email, for example, use -the first line on the Subject line and the rest of the commit in the -body. +description. The text up to the first blank line in a commit +message is treated as the commit title, and that title is used +throughout git. For example, linkgit:git-format-patch[1] turns a +commit into email, and it uses the title on the Subject line and the +rest of the commit in the body. + [[ignoring-files]] Ignoring files |