diff options
Diffstat (limited to 'Documentation')
97 files changed, 1410 insertions, 408 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 8346c19..1b1c45d 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -31,29 +31,36 @@ But if you must have a list of rules, here they are. For shell scripts specifically (not exhaustive): + - We use tabs for indentation. + + - Case arms are indented at the same depth as case and esac lines. + - We prefer $( ... ) for command substitution; unlike ``, it properly nests. It should have been the way Bourne spelled it from day one, but unfortunately isn't. - - We use ${parameter-word} and its [-=?+] siblings, and their - colon'ed "unset or null" form. + - We use POSIX compliant parameter substitutions and avoid bashisms; + namely: - - We use ${parameter#word} and its [#%] siblings, and their - doubled "longest matching" form. + - We use ${parameter-word} and its [-=?+] siblings, and their + colon'ed "unset or null" form. - - We use Arithmetic Expansion $(( ... )). + - We use ${parameter#word} and its [#%] siblings, and their + doubled "longest matching" form. - - Inside Arithmetic Expansion, spell shell variables with $ in front - of them, as some shells do not grok $((x)) while accepting $(($x)) - just fine (e.g. dash older than 0.5.4). + - No "Substring Expansion" ${parameter:offset:length}. - - No "Substring Expansion" ${parameter:offset:length}. + - No shell arrays. - - No shell arrays. + - No strlen ${#parameter}. - - No strlen ${#parameter}. + - No pattern replacement ${parameter/pattern/string}. - - No regexp ${parameter/pattern/string}. + - We use Arithmetic Expansion $(( ... )). + + - Inside Arithmetic Expansion, spell shell variables with $ in front + of them, as some shells do not grok $((x)) while accepting $(($x)) + just fine (e.g. dash older than 0.5.4). - We do not use Process Substitution <(list) or >(list). @@ -136,3 +143,55 @@ For C programs: - When we pass <string, length> pair to functions, we should try to pass them in that order. + +Writing Documentation: + + Every user-visible change should be reflected in the documentation. + The same general rule as for code applies -- imitate the existing + conventions. A few commented examples follow to provide reference + when writing or modifying command usage strings and synopsis sections + in the manual pages: + + Placeholders are enclosed in angle brackets: + <file> + --sort=<key> + --abbrev[=<n>] + + Possibility of multiple occurences is indicated by three dots: + <file>... + (One or more of <file>.) + + Optional parts are enclosed in square brackets: + [<extra>] + (Zero or one <extra>.) + + --exec-path[=<path>] + (Option with an optional argument. Note that the "=" is inside the + brackets.) + + [<patch>...] + (Zero or more of <patch>. Note that the dots are inside, not + outside the brackets.) + + Multiple alternatives are indicated with vertical bar: + [-q | --quiet] + [--utf8 | --no-utf8] + + Parentheses are used for grouping: + [(<rev>|<range>)...] + (Any number of either <rev> or <range>. Parens are needed to make + it clear that "..." pertains to both <rev> and <range>.) + + [(-p <parent>)...] + (Any number of option -p, each with one <parent> argument.) + + git remote set-head <name> (-a | -d | <branch>) + (One and only one of "-a", "-d" or "<branch>" _must_ (no square + brackets) be provided.) + + And a somewhat more contrived example: + --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]] + Here "=" is outside the brackets, because "--diff-filter=" is a + valid usage. "*" has its own pair of brackets, because it can + (optionally) be specified only when one or more of the letters is + also provided. diff --git a/Documentation/RelNotes/1.7.0.8.txt b/Documentation/RelNotes/1.7.0.8.txt new file mode 100644 index 0000000..7f05b48 --- /dev/null +++ b/Documentation/RelNotes/1.7.0.8.txt @@ -0,0 +1,10 @@ +Git v1.7.0.8 Release Notes +========================== + +This is primarily to backport support for the new "add.ignoreErrors" +name given to the existing "add.ignore-errors" configuration variable. + +The next version, Git 1.7.4, and future versions, will support both +old and incorrect name and the new corrected name, but without this +backport, users who want to use the new name "add.ignoreErrors" in +their repositories cannot use older versions of Git. diff --git a/Documentation/RelNotes/1.7.1.3.txt b/Documentation/RelNotes/1.7.1.3.txt new file mode 100644 index 0000000..5b18518 --- /dev/null +++ b/Documentation/RelNotes/1.7.1.3.txt @@ -0,0 +1,10 @@ +Git v1.7.1.3 Release Notes +========================== + +This is primarily to backport support for the new "add.ignoreErrors" +name given to the existing "add.ignore-errors" configuration variable. + +The next version, Git 1.7.4, and future versions, will support both +old and incorrect name and the new corrected name, but without this +backport, users who want to use the new name "add.ignoreErrors" in +their repositories cannot use older versions of Git. diff --git a/Documentation/RelNotes/1.7.2.4.txt b/Documentation/RelNotes/1.7.2.4.txt new file mode 100644 index 0000000..f7950a4 --- /dev/null +++ b/Documentation/RelNotes/1.7.2.4.txt @@ -0,0 +1,10 @@ +Git v1.7.2.4 Release Notes +========================== + +This is primarily to backport support for the new "add.ignoreErrors" +name given to the existing "add.ignore-errors" configuration variable. + +The next version, Git 1.7.4, and future versions, will support both +old and incorrect name and the new corrected name, but without this +backport, users who want to use the new name "add.ignoreErrors" in +their repositories cannot use older versions of Git. diff --git a/Documentation/RelNotes/1.7.3.2.txt b/Documentation/RelNotes/1.7.3.2.txt new file mode 100644 index 0000000..5c93b85 --- /dev/null +++ b/Documentation/RelNotes/1.7.3.2.txt @@ -0,0 +1,5 @@ +Git v1.7.3.2 Release Notes +========================== + +This is primarily to push out many documentation fixes accumulated since +the 1.7.3.1 release. diff --git a/Documentation/RelNotes/1.7.3.3.txt b/Documentation/RelNotes/1.7.3.3.txt new file mode 100644 index 0000000..9b2b244 --- /dev/null +++ b/Documentation/RelNotes/1.7.3.3.txt @@ -0,0 +1,54 @@ +Git v1.7.3.3 Release Notes +========================== + +In addition to the usual fixes, this release also includes support for +the new "add.ignoreErrors" name given to the existing "add.ignore-errors" +configuration variable. + +The next version, Git 1.7.4, and future versions, will support both +old and incorrect name and the new corrected name, but without this +backport, users who want to use the new name "add.ignoreErrors" in +their repositories cannot use older versions of Git. + +Fixes since v1.7.3.2 +-------------------- + + * "git apply" segfaulted when a bogus input is fed to it. + + * Running "git cherry-pick --ff" on a root commit segfaulted. + + * "diff", "blame" and friends incorrectly applied textconv filters to + symlinks. + + * Highlighting of whitespace breakage in "diff" output was showing + incorrect amount of whitespaces when blank-at-eol is set and the line + consisted only of whitespaces and a TAB. + + * "diff" was overly inefficient when trying to find the line to use for + the function header (i.e. equivalent to --show-c-function of GNU diff). + + * "git imap-send" depends on libcrypto but our build rule relied on the + linker to implicitly link it via libssl, which was wrong. + + * "git merge-file" can be called from within a subdirectory now. + + * "git repack -f" expanded and recompressed non-delta objects in the + existing pack, which was wasteful. Use new "-F" option if you really + want to (e.g. when changing the pack.compression level). + + * "git rev-list --format="...%x00..." incorrectly chopped its output + at NUL. + + * "git send-email" did not correctly remove duplicate mail addresses from + the Cc: header that appear on the To: header. + + * The completion script (in contrib/completion) ignored lightweight tags + in __git_ps1(). + + * "git-blame" mode (in contrib/emacs) didn't say (require 'format-spec) + even though it depends on it; it didn't work with Emacs 22 or older + unless Gnus is used. + + * "git-p4" (in contrib/) did not correctly handle deleted files. + +Other minor fixes and documentation updates are also included. diff --git a/Documentation/RelNotes/1.7.3.4.txt b/Documentation/RelNotes/1.7.3.4.txt new file mode 100644 index 0000000..925178f --- /dev/null +++ b/Documentation/RelNotes/1.7.3.4.txt @@ -0,0 +1,32 @@ +Git v1.7.3.4 Release Notes +========================== + +Fixes since v1.7.3.3 +-------------------- + + * Smart HTTP transport used to incorrectly retry redirected POST + request with GET request. + + * "git apply" did not correctly handle patches that only change modes + if told to apply while stripping leading paths with -p option. + + * "git apply" can deal with patches with timezone formatted with a + colon between the hours and minutes part (e.g. "-08:00" instead of + "-0800"). + + * "git cherry-pick" or "git revert" refused to work when a path that + would be modified by the operation was stat-dirty without a real + difference in the contents of the file. + + * "git diff --check" reported an incorrect line number for added + blank lines at the end of file. + + * Setting log.decorate configuration variable to "0" or "1" to mean + "false" or "true" did not work. + + * "git tag -v" did not work with GPG signatures in rfc1991 mode. + + * The post-receive-email sample hook was accidentally broken in 1.7.3.3 + update. + +Other minor fixes and documentation updates are also included. diff --git a/Documentation/RelNotes/1.7.4.txt b/Documentation/RelNotes/1.7.4.txt new file mode 100644 index 0000000..c1d0669 --- /dev/null +++ b/Documentation/RelNotes/1.7.4.txt @@ -0,0 +1,119 @@ +Git v1.7.4 Release Notes (draft) +================================ + +Updates since v1.7.3 +-------------------- + + * The option parsers of various commands that create new branch (or + rename existing ones to a new name) were too loose and users were + allowed to call a branch with a name that begins with a dash by + creative abuse of their command line options, which only lead to + burn themselves. The name of a branch cannot begin with a dash + now. + + * System-wide fallback default attributes can be stored in + /etc/gitattributes; core.attributesfile configuration variable can + be used to customize the path to this file. + + * The thread structure generated by "git send-email" has changed + slightly. Setting the cover letter of the latest series as a reply + to the cover letter of the previous series with --in-reply-to used + to make the new cover letter and all the patches replies to the + cover letter of the previous series; this has been changed to make + the patches in the new series replies to the new cover letter. + + * Bash completion script in contrib/ has been adjusted to be also + usable by zsh. + + * "git blame" learned --show-email option to display the e-mail + addresses instead of the names of authors. + + * "git daemon" can be built in MinGW environment. + + * "git daemon" can take more than one --listen option to listen to + multiple addresses. + + * "git diff" and "git grep" learned how functions and subroutines + in Fortran look like. + + * "git mergetool" tells vim/gvim to show three-way diff by default + (use vimdiff2/gvimdiff2 as the tool name for old behaviour). + + * "git log -G<pattern>" limits the output to commits whose change has + added or deleted lines that match the given pattern. + + * "git read-tree" with no argument as a way to empty the index is + deprecated; we might want to remove it in the future. Users can + use the new --empty option to be more explicit instead. + + * "git repack -f" does not spend cycles to recompress objects in the + non-delta representation anymore (use -F if you really mean it when + e.g. you changed the compression level). + + * "git merge --log" used to limit the resulting merge log to 20 + entries; this is now customizable by giving e.g. "--log=47". + + * "git merge" may work better when all files were moved out of a + directory in one branch while a new file is created in place of that + directory in the other branch. + + * "git rebase --autosquash" can use SHA-1 object names to name which + commit to fix up (e.g. "fixup! e83c5163"). + + * The default "recursive" merge strategy learned --rename-threshold + option to influence the rename detection, similar to the -M option + of "git diff". E.g. "git merge -Xrename-threshold=50% ..." to use + this. + + * The "recursive" strategy also learned to ignore various whitespace + changes; the most notable is -Xignore-space-at-eol. + + * "git send-email" learned "--to-cmd", similar to "--cc-cmd", to read + recipient list from a command output. + + * "git send-email" learned to read and use "To:" from its input files. + + * you can extend "git shell", which is often used on boxes that allow + git-only login over ssh as login shell, with custom set of + commands. + + * "git submodule sync" updates metainformation for all submodules, + not just the ones that have been checked out. + + * gitweb can use custom 'highlight' command with its configuration file. + + +Also contains various documentation updates. + + +Fixes since v1.7.3 +------------------ + +All of the fixes in v1.7.3.X maintenance series are included in this +release, unless otherwise noted. + + * "git checkout" removed an untracked file "foo" from the working + tree when switching to a branch that contains a tracked path + "foo/bar". Prevent this, just like the case where the conflicting + path were "foo" (c752e7f..7980872d). + + * "git log --author=me --author=her" did not find commits written by + me or by her; instead it looked for commits written by me and by + her, which is impossible. + + * "git merge" into an unborn branch removed an untracked file "foo" + from the working tree when merged branch had "foo" (2caf20c..172b642). + + * "git push --progress" shows progress indicators now. + + * "git repack" places its temporary packs under $GIT_OBJECT_DIRECTORY/pack + instead of $GIT_OBJECT_DIRECTORY/ to avoid cross directory renames. + + * "git submodule update --recursive --other-flags" passes flags down + to its subinvocations. + +--- +exec >/var/tmp/1 +O=v1.7.3.2-450-g5b9c331 +echo O=$(git describe master) +git shortlog --no-merges ^maint ^$O master diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index ece3c77..72741eb 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -264,12 +264,21 @@ the change to its true author (see (2) above). Also notice that a real name is used in the Signed-off-by: line. Please don't hide your real name. -Some people also put extra tags at the end. - -"Acked-by:" says that the patch was reviewed by the person who -is more familiar with the issues and the area the patch attempts -to modify. "Tested-by:" says the patch was tested by the person -and found to have the desired effect. +If you like, you can put extra tags at the end: + +1. "Reported-by:" is used to to credit someone who found the bug that + the patch attempts to fix. +2. "Acked-by:" says that the person who is more familiar with the area + the patch attempts to modify liked the patch. +3. "Reviewed-by:", unlike the other tags, can only be offered by the + reviewer and means that she is completely satisfied that the patch + is ready for application. It is usually offered only after a + detailed review. +4. "Tested-by:" is used to indicate that the person applied the patch + and found it to have the desired effect. + +You can also create your own tag or use one that's in common usage +such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". ------------------------------------------------ An ideal patch flow diff --git a/Documentation/config.txt b/Documentation/config.txt index d82c0da..0f85793 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -374,6 +374,15 @@ core.warnAmbiguousRefs:: If true, git will warn you if the ref name you passed it is ambiguous and might match multiple refs in the .git/refs/ tree. True by default. +core.abbrevguard:: + Even though git makes sure that it uses enough hexdigits to show + an abbreviated object name unambiguously, as more objects are + added to the repository over time, a short name that used to be + unique will stop being unique. Git uses this many extra hexdigits + that are more than necessary to make the object name currently + unique, in the hope that its output will stay unique a bit longer. + Defaults to 0. + core.compression:: An integer -1..9, indicating a default compression level. -1 is the zlib default. 0 means no compression, @@ -459,6 +468,12 @@ core.askpass:: prompt. The external program shall be given a suitable prompt as command line argument and write the password on its STDOUT. +core.attributesfile:: + In addition to '.gitattributes' (per-directory) and + '.git/info/attributes', git looks into this file for attributes + (see linkgit:gitattributes[5]). Path expansions are made the same + way as for `core.excludesfile`. + core.editor:: Commands such as `commit` and `tag` that lets you edit messages by launching an editor uses the value of this @@ -548,9 +563,13 @@ core.sparseCheckout:: linkgit:git-read-tree[1] for more information. add.ignore-errors:: +add.ignoreErrors:: Tells 'git add' to continue adding files when some files cannot be added due to indexing errors. Equivalent to the '--ignore-errors' - option of linkgit:git-add[1]. + option of linkgit:git-add[1]. Older versions of git accept only + `add.ignore-errors`, which does not follow the usual naming + convention for configuration variables. Newer versions of git + honor `add.ignoreErrors` as well. alias.*:: Command aliases for the linkgit:git[1] command wrapper - e.g. @@ -595,8 +614,9 @@ branch.autosetupmerge:: this behavior can be chosen per-branch using the `--track` and `--no-track` options. The valid settings are: `false` -- no automatic setup is done; `true` -- automatic setup is done when the - starting point is a remote branch; `always` -- automatic setup is - done when the starting point is either a local branch or remote + starting point is a remote-tracking branch; `always` -- + automatic setup is done when the starting point is either a + local branch or remote-tracking branch. This option defaults to true. branch.autosetuprebase:: @@ -607,7 +627,7 @@ branch.autosetuprebase:: When `local`, rebase is set to true for tracked branches of other local branches. When `remote`, rebase is set to true for tracked branches of - remote branches. + remote-tracking branches. When `always`, rebase will be set to true for all tracking branches. See "branch.autosetupmerge" for details on how to set up a @@ -674,7 +694,7 @@ color.branch:: color.branch.<slot>:: Use customized color for branch coloration. `<slot>` is one of `current` (the current branch), `local` (a local branch), - `remote` (a tracking branch in refs/remotes/), `plain` (other + `remote` (a remote-tracking branch in refs/remotes/), `plain` (other refs). + The value for these configuration variables is a list of colors (at most @@ -702,7 +722,7 @@ color.diff.<slot>:: color.decorate.<slot>:: Use customized color for 'git log --decorate' output. `<slot>` is one of `branch`, `remoteBranch`, `tag`, `stash` or `HEAD` for local - branches, remote tracking branches, tags, stash and HEAD, respectively. + branches, remote-tracking branches, tags, stash and HEAD, respectively. color.grep:: When set to `always`, always highlight matches. When `false` (or @@ -1096,7 +1116,7 @@ gui.newbranchtemplate:: linkgit:git-gui[1]. gui.pruneduringfetch:: - "true" if linkgit:git-gui[1] should prune tracking branches when + "true" if linkgit:git-gui[1] should prune remote-tracking branches when performing a fetch. The default value is "false". gui.trustmtime:: @@ -1466,6 +1486,10 @@ pack.compression:: not set, defaults to -1, the zlib default, which is "a default compromise between speed and compression (currently equivalent to level 6)." ++ +Note that changing the compression level will not automatically recompress +all existing objects. You can force recompression by passing the -F option +to linkgit:git-repack[1]. pack.deltaCacheSize:: The maximum memory in bytes used for caching deltas in @@ -1521,11 +1545,13 @@ pack.packSizeLimit:: supported. pager.<cmd>:: - Allows turning on or off pagination of the output of a - particular git subcommand when writing to a tty. If - `\--paginate` or `\--no-pager` is specified on the command line, - it takes precedence over this option. To disable pagination for - all commands, set `core.pager` or `GIT_PAGER` to `cat`. + If the value is boolean, turns on or off pagination of the + output of a particular git subcommand when writing to a tty. + Otherwise, turns on pagination for the subcommand using the + pager specified by the value of `pager.<cmd>`. If `\--paginate` + or `\--no-pager` is specified on the command line, it takes + precedence over this option. To disable pagination for all + commands, set `core.pager` or `GIT_PAGER` to `cat`. pretty.<name>:: Alias for a --pretty= format string, as specified in @@ -1550,12 +1576,12 @@ push.default:: no refspec is implied by any of the options given on the command line. Possible values are: + -* `nothing` do not push anything. -* `matching` push all matching branches. +* `nothing` - do not push anything. +* `matching` - push all matching branches. All branches having the same name in both ends are considered to be matching. This is the default. -* `tracking` push the current branch to its upstream branch. -* `current` push the current branch to a branch of the same name. +* `tracking` - push the current branch to its upstream branch. +* `current` - push the current branch to a branch of the same name. rebase.stat:: Whether to show a diffstat of what changed upstream since the last @@ -1727,6 +1753,7 @@ sendemail.to:: sendemail.smtpdomain:: sendemail.smtpserver:: sendemail.smtpserverport:: +sendemail.smtpserveroption:: sendemail.smtpuser:: sendemail.thread:: sendemail.validate:: @@ -1755,9 +1782,9 @@ status.showUntrackedFiles:: the untracked files. Possible values are: + -- - - 'no' - Show no untracked files - - 'normal' - Shows untracked files and directories - - 'all' - Shows also individual files in untracked directories. +* `no` - Show no untracked files. +* `normal` - Show untracked files and directories. +* `all` - Show also individual files in untracked directories. -- + If this variable is not specified, it defaults to 'normal'. diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 8f9a241..3ac2bea 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -9,16 +9,15 @@ patch file. You can customize the creation of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables. What the -p option produces is slightly different from the traditional -diff format. +diff format: -1. It is preceded with a "git diff" header, that looks like - this: +1. It is preceded with a "git diff" header that looks like this: diff --git a/file1 b/file2 + The `a/` and `b/` filenames are the same unless rename/copy is involved. Especially, even for a creation or a deletion, -`/dev/null` is _not_ used in place of `a/` or `b/` filenames. +`/dev/null` is _not_ used in place of the `a/` or `b/` filenames. + When rename/copy is involved, `file1` and `file2` show the name of the source file of the rename/copy and the name of @@ -37,18 +36,39 @@ the file that rename/copy produces, respectively. similarity index <number> dissimilarity index <number> index <hash>..<hash> <mode> - -3. TAB, LF, double quote and backslash characters in pathnames - are represented as `\t`, `\n`, `\"` and `\\`, respectively. - If there is need for such substitution then the whole - pathname is put in double quotes. - ++ +File modes are printed as 6-digit octal numbers including the file type +and file permission bits. ++ +Path names in extended headers do not include the `a/` and `b/` prefixes. ++ The similarity index is the percentage of unchanged lines, and the dissimilarity index is the percentage of changed lines. It is a rounded down integer, followed by a percent sign. The similarity index value of 100% is thus reserved for two equal files, while 100% dissimilarity means that no line from the old file made it into the new one. ++ +The index line includes the SHA-1 checksum before and after the change. +The <mode> is included if the file mode does not change; otherwise, +separate lines indicate the old and the new mode. + +3. TAB, LF, double quote and backslash characters in pathnames + are represented as `\t`, `\n`, `\"` and `\\`, respectively. + If there is need for such substitution then the whole + pathname is put in double quotes. + +4. All the `file1` files in the output refer to files before the + commit, and all the `file2` files refer to files after the commit. + It is incorrect to apply each change to each file sequentially. For + example, this patch will swap a and b: + + diff --git a/a b/b + rename from a + rename to b + diff --git a/b b/a + rename from b + rename to a combined diff format diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 4656a97..f3e9538 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -48,9 +48,9 @@ endif::git-format-patch[] --patience:: Generate a diff using the "patience diff" algorithm. ---stat[=width[,name-width]]:: +--stat[=<width>[,<name-width>]]:: Generate a diffstat. You can override the default - output width for 80-column terminal by `--stat=width`. + output width for 80-column terminal by `--stat=<width>`. The width of the filename part can be controlled by giving another width to it separated by a comma. @@ -66,14 +66,14 @@ endif::git-format-patch[] number of modified files, as well as number of added and deleted lines. ---dirstat[=limit]:: +--dirstat[=<limit>]:: Output the distribution of relative amount of changes (number of lines added or removed) for each sub-directory. Directories with changes below a cut-off percent (3% by default) are not shown. The cut-off percent - can be set with `--dirstat=limit`. Changes in a child directory is not + can be set with `--dirstat=<limit>`. Changes in a child directory are not counted for the parent directory, unless `--cumulative` is used. ---dirstat-by-file[=limit]:: +--dirstat-by-file[=<limit>]:: Same as `--dirstat`, but counts changed files instead of lines. --summary:: @@ -207,6 +207,7 @@ endif::git-format-patch[] digits can be specified with `--abbrev=<n>`. -B[<n>][/<m>]:: +--break-rewrites[=[<n>][/<m>]]:: Break complete rewrite changes into pairs of delete and create. This serves two purposes: + @@ -229,6 +230,7 @@ eligible for being picked up as a possible source of a rename to another file. -M[<n>]:: +--detect-renames[=<n>]:: ifndef::git-log[] Detect renames. endif::git-log[] @@ -244,23 +246,10 @@ endif::git-log[] hasn't changed. -C[<n>]:: +--detect-copies[=<n>]:: Detect copies as well as renames. See also `--find-copies-harder`. If `n` is specified, it has the same meaning as for `-M<n>`. -ifndef::git-format-patch[] ---diff-filter=[ACDMRTUXB*]:: - Select only files that are Added (`A`), Copied (`C`), - Deleted (`D`), Modified (`M`), Renamed (`R`), have their - type (i.e. regular file, symlink, submodule, ...) changed (`T`), - are Unmerged (`U`), are - Unknown (`X`), or have had their pairing Broken (`B`). - Any combination of the filter characters may be used. - When `*` (All-or-none) is added to the combination, all - paths are selected if there is any file that matches - other criteria in the comparison; if there is no file - that matches other criteria, nothing is selected. -endif::git-format-patch[] - --find-copies-harder:: For performance reasons, by default, `-C` option finds copies only if the original file of the copy was modified in the same @@ -278,14 +267,30 @@ endif::git-format-patch[] number. ifndef::git-format-patch[] +--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]:: + Select only files that are Added (`A`), Copied (`C`), + Deleted (`D`), Modified (`M`), Renamed (`R`), have their + type (i.e. regular file, symlink, submodule, ...) changed (`T`), + are Unmerged (`U`), are + Unknown (`X`), or have had their pairing Broken (`B`). + Any combination of the filter characters (including none) can be used. + When `*` (All-or-none) is added to the combination, all + paths are selected if there is any file that matches + other criteria in the comparison; if there is no file + that matches other criteria, nothing is selected. + -S<string>:: Look for differences that introduce or remove an instance of <string>. Note that this is different than the string simply appearing in diff output; see the 'pickaxe' entry in linkgit:gitdiffcore[7] for more details. +-G<regex>:: + Look for differences whose added or removed line matches + the given <regex>. + --pickaxe-all:: - When `-S` finds a change, show all the changes in that + When `-S` or `-G` finds a change, show all the changes in that changeset, not just the files that contain the change in <string>. diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index e0ba8cc..ae413e5 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -180,12 +180,12 @@ directory; clone from it to start a repository on the satellite machine. <2> clone sets these configuration variables by default. It arranges `git pull` to fetch and store the branches of mothership -machine to local `remotes/origin/*` tracking branches. +machine to local `remotes/origin/*` remote-tracking branches. <3> arrange `git push` to push local `master` branch to `remotes/satellite/master` branch of the mothership machine. <4> push will stash our work away on `remotes/satellite/master` -tracking branch on the mothership machine. You could use this as -a back-up method. +remote-tracking branch on the mothership machine. You could use this +as a back-up method. <5> on mothership machine, merge the work done on the satellite machine into the master branch. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 470ac31..678675c 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -36,7 +36,7 @@ ifndef::git-pull[] -p:: --prune:: - After fetching, remove any remote tracking branches which + After fetching, remove any remote-tracking branches which no longer exist on the remote. endif::git-pull[] @@ -53,6 +53,7 @@ endif::git-pull[] behavior for a remote may be specified with the remote.<name>.tagopt setting. See linkgit:git-config[1]. +ifndef::git-pull[] -t:: --tags:: Most of the tags are fetched automatically as branch @@ -63,6 +64,7 @@ endif::git-pull[] downloaded. The default behavior for a remote may be specified with the remote.<name>.tagopt setting. See linkgit:git-config[1]. +endif::git-pull[] -u:: --update-head-ok:: diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 73378b2..54aaaeb 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -92,9 +92,11 @@ See ``Interactive mode'' for details. edit it. After the editor was closed, adjust the hunk headers and apply the patch to the index. + -*NOTE*: Obviously, if you change anything else than the first character -on lines beginning with a space or a minus, the patch will no longer -apply. +The intent of this option is to pick and choose lines of the patch to +apply, or even to modify the contents of lines to be staged. This can be +quicker and more flexible than using the interactive hunk selector. +However, it is easy to confuse oneself and create a patch that does not +apply to the index. See EDITING PATCHES below. -u:: --update:: @@ -295,6 +297,78 @@ diff:: This lets you review what will be committed (i.e. between HEAD and index). + +EDITING PATCHES +--------------- + +Invoking `git add -e` or selecting `e` from the interactive hunk +selector will open a patch in your editor; after the editor exits, the +result is applied to the index. You are free to make arbitrary changes +to the patch, but note that some changes may have confusing results, or +even result in a patch that cannot be applied. If you want to abort the +operation entirely (i.e., stage nothing new in the index), simply delete +all lines of the patch. The list below describes some common things you +may see in a patch, and which editing operations make sense on them. + +-- +added content:: + +Added content is represented by lines beginning with "{plus}". You can +prevent staging any addition lines by deleting them. + +removed content:: + +Removed content is represented by lines beginning with "-". You can +prevent staging their removal by converting the "-" to a " " (space). + +modified content:: + +Modified content is represented by "-" lines (removing the old content) +followed by "{plus}" lines (adding the replacement content). You can +prevent staging the modification by converting "-" lines to " ", and +removing "{plus}" lines. Beware that modifying only half of the pair is +likely to introduce confusing changes to the index. +-- + +There are also more complex operations that can be performed. But beware +that because the patch is applied only to the index and not the working +tree, the working tree will appear to "undo" the change in the index. +For example, introducing a a new line into the index that is in neither +the HEAD nor the working tree will stage the new line for commit, but +the line will appear to be reverted in the working tree. + +Avoid using these constructs, or do so with extreme caution. + +-- +removing untouched content:: + +Content which does not differ between the index and working tree may be +shown on context lines, beginning with a " " (space). You can stage +context lines for removal by converting the space to a "-". The +resulting working tree file will appear to re-add the content. + +modifying existing content:: + +One can also modify context lines by staging them for removal (by +converting " " to "-") and adding a "{plus}" line with the new content. +Similarly, one can modify "{plus}" lines for existing additions or +modifications. In all cases, the new modification will appear reverted +in the working tree. + +new content:: + +You may also add new content that does not exist in the patch; simply +add new lines, each starting with "{plus}". The addition will appear +reverted in the working tree. +-- + +There are also several operations which should be avoided entirely, as +they will make the patch impossible to apply: + +* adding context (" ") or removal ("-") lines +* deleting context or removal lines +* modifying the contents of context or removal lines + SEE ALSO -------- linkgit:git-status[1] diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 9e62f87..51297d0 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -14,7 +14,7 @@ SYNOPSIS [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] [--reject] [-q | --quiet] [--scissors | --no-scissors] - [<mbox> | <Maildir>...] + [(<mbox> | <Maildir>)...] 'git am' (--continue | --skip | --abort) DESCRIPTION @@ -25,7 +25,7 @@ current branch. OPTIONS ------- -<mbox>|<Maildir>...:: +(<mbox>|<Maildir>)...:: The list of mailbox files to read patches from. If you do not supply this argument, the command reads from the standard input. If you supply directories, they will be treated as Maildirs. diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 4a74b23..881652f 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -12,10 +12,10 @@ SYNOPSIS 'git apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] - [-pNUM] [-CNUM] [--inaccurate-eof] [--recount] [--cached] + [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached] [--ignore-space-change | --ignore-whitespace ] - [--whitespace=<nowarn|warn|fix|error|error-all>] - [--exclude=PATH] [--include=PATH] [--directory=<root>] + [--whitespace=(nowarn|warn|fix|error|error-all)] + [--exclude=<path>] [--include=<path>] [--directory=<root>] [--verbose] [<patch>...] DESCRIPTION diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index 4f358c8..2411ce5 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -109,7 +109,7 @@ OPTIONS Author ------ -Written by Martin Langhoff <martin@catalyst.net.nz>. +Written by Martin Langhoff <martin@laptop.org>. Documentation -------------- diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 8d3e666..4163a1b 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>] [-o | --output=<file>] [--worktree-attributes] [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish> - [path...] + [<path>...] DESCRIPTION ----------- @@ -73,7 +73,7 @@ OPTIONS <tree-ish>:: The tree or commit to produce an archive for. -path:: +<path>:: Without an optional path parameter, all files and subdirectories of the current working directory are included in the archive. If one or more paths are specified, only these are included. diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index a27f439..c71671b 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -8,7 +8,7 @@ git-blame - Show what revision and author last modified each line of a file SYNOPSIS -------- [verse] -'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-p] [-w] [--incremental] [-L n,m] +'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L n,m] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [<rev> | --contents <file> | --reverse <rev>] [--] <file> @@ -65,6 +65,10 @@ include::blame-options.txt[] -s:: Suppress the author name and timestamp from the output. +-e:: +--show-email:: + Show the author email instead of author name (Default: off). + -w:: Ignore whitespace when comparing the parent's version and the child's to find where the lines came from. diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 1940256..9106d38 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -37,11 +37,12 @@ Note that this will create the new branch, but it will not switch the working tree to it; use "git checkout <newbranch>" to switch to the new branch. -When a local branch is started off a remote branch, git sets up the +When a local branch is started off a remote-tracking branch, git sets up the branch so that 'git pull' will appropriately merge from -the remote branch. This behavior may be changed via the global +the remote-tracking branch. This behavior may be changed via the global `branch.autosetupmerge` configuration flag. That setting can be -overridden by using the `--track` and `--no-track` options. +overridden by using the `--track` and `--no-track` options, and +changed later using `git branch --set-upstream`. With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>. If <oldbranch> had a corresponding reflog, it is renamed to match @@ -89,7 +90,8 @@ OPTIONS Move/rename a branch even if the new branch name already exists. --color[=<when>]:: - Color branches to highlight current, local, and remote branches. + Color branches to highlight current, local, and + remote-tracking branches. The value must be always (the default), never, or auto. --no-color:: @@ -125,11 +127,11 @@ OPTIONS it directs `git pull` without arguments to pull from the upstream when the new branch is checked out. + -This behavior is the default when the start point is a remote branch. +This behavior is the default when the start point is a remote-tracking branch. Set the branch.autosetupmerge configuration variable to `false` if you want `git checkout` and `git branch` to always behave as if '--no-track' were given. Set it to `always` if you want this behavior when the -start-point is either a local or remote branch. +start-point is either a local or remote-tracking branch. --no-track:: Do not set up "upstream" configuration, even if the diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 38e59af..6266a3a 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -11,8 +11,8 @@ SYNOPSIS [verse] 'git bundle' create <file> <git-rev-list-args> 'git bundle' verify <file> -'git bundle' list-heads <file> [refname...] -'git bundle' unbundle <file> [refname...] +'git bundle' list-heads <file> [<refname>...] +'git bundle' unbundle <file> [<refname>...] DESCRIPTION ----------- @@ -68,7 +68,7 @@ unbundle <file>:: packaged. -[refname...]:: +[<refname>...]:: A list of references used to limit the references reported as available. This is principally of use to 'git fetch', which expects to receive only those references asked for and not diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index a3f56b0..544ba7b 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -27,7 +27,7 @@ OPTIONS <object>:: The name of the object to show. For a more complete list of ways to spell object names, see - the "SPECIFYING REVISIONS" section in linkgit:gitrevisions[1]. + the "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. -t:: Instead of the content, show the object type identified by diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index f5c2e06..205d83d 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -49,7 +49,7 @@ git imposes the following rules on how references are named: These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used unquoted (by mistake), and also avoids ambiguities in certain -reference name expressions (see linkgit:gitrevisions[1]): +reference name expressions (see linkgit:gitrevisions[7]): . A double-dot `..` is often used as in `ref1..ref2`, and in some contexts this notation means `{caret}ref1 ref2` (i.e. not in diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 62f9ab2..0c0a9c1 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -13,7 +13,7 @@ SYNOPSIS [--stage=<number>|all] [--temp] [-z] [--stdin] - [--] [<file>]* + [--] [<file>...] DESCRIPTION ----------- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 22d3611..880763d 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -98,7 +98,7 @@ entries; instead, unmerged entries are ignored. "--track" in linkgit:git-branch[1] for details. + If no '-b' option is given, the name of the new branch will be -derived from the remote branch. If "remotes/" or "refs/remotes/" +derived from the remote-tracking branch. If "remotes/" or "refs/remotes/" is prefixed it is stripped away, and then the part up to the next slash (which would be the nickname of the remote) is removed. This would tell us to use "hack" as the local branch when branching diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 2cef579..7300870 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -21,7 +21,7 @@ OPTIONS <commit>...:: Commits to cherry-pick. For a more complete list of ways to spell commits, see - linkgit:gitrevisions[1]. + linkgit:gitrevisions[7]. Sets of commits can be passed but no traversal is done by default, as if the '--no-walk' option was specified, see linkgit:git-rev-list[1]. @@ -92,7 +92,7 @@ git cherry-pick ^HEAD master:: Apply the changes introduced by all commits that are ancestors of master but not of HEAD to produce new commits. -git cherry-pick master\~4 master~2:: +git cherry-pick master{tilde}4 master{tilde}2:: Apply the changes introduced by the fifth and third last commits pointed to by master and create 2 new commits with diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index ab72933..42e7021 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -12,7 +12,8 @@ SYNOPSIS 'git clone' [--template=<template_directory>] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] - [--depth <depth>] [--recursive] [--] <repository> [<directory>] + [--depth <depth>] [--recursive|--recurse-submodules] [--] <repository> + [<directory>] DESCRIPTION ----------- @@ -131,7 +132,7 @@ objects from the source repository into a pack in the cloned repository. Set up a mirror of the source repository. This implies `--bare`. Compared to `--bare`, `--mirror` not only maps local branches of the source to local branches of the target, it maps all refs (including - remote branches, notes etc.) and sets up a refspec configuration such + remote-tracking branches, notes etc.) and sets up a refspec configuration such that all these refs are overwritten by a `git remote update` in the target repository. @@ -167,6 +168,7 @@ objects from the source repository into a pack in the cloned repository. as patches. --recursive:: +--recurse-submodules:: After the clone is created, initialize all submodules within, using their default settings. This is equivalent to running `git submodule update --init --recursive` immediately after diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 349366e..5dcf427 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object SYNOPSIS -------- -'git commit-tree' <tree> [-p <parent commit>]* < changelog +'git commit-tree' <tree> [(-p <parent commit>)...] < changelog DESCRIPTION ----------- diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 42fb1f5..b586c0f 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -9,10 +9,10 @@ SYNOPSIS -------- [verse] 'git commit' [-a | --interactive] [-s] [-v] [-u<mode>] [--amend] [--dry-run] - [(-c | -C) <commit>] [-F <file> | -m <msg>] [--reset-author] - [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=<author>] - [--date=<date>] [--cleanup=<mode>] [--status | --no-status] [--] - [[-i | -o ]<file>...] + [(-c | -C | --fixup | --squash) <commit>] [-F <file> | -m <msg>] + [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] + [-e] [--author=<author>] [--date=<date>] [--cleanup=<mode>] + [--status | --no-status] [-i | -o] [--] [<file>...] DESCRIPTION ----------- @@ -70,6 +70,19 @@ OPTIONS Like '-C', but with '-c' the editor is invoked, so that the user can further edit the commit message. +--fixup=<commit>:: + Construct a commit message for use with `rebase --autosquash`. + The commit message will be the subject line from the specified + commit with a prefix of "fixup! ". See linkgit:git-rebase[1] + for details. + +--squash=<commit>:: + Construct a commit message for use with `rebase --autosquash`. + The commit message subject line is taken from the specified + commit with a prefix of "squash! ". Can be used with additional + commit message options (`-m`/`-c`/`-C`/`-F`). See + linkgit:git-rebase[1] for details. + --reset-author:: When used with -C/-c/--amend options, declare that the authorship of the resulting commit now belongs of the committer. diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index b2696ef..d25661e 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -114,11 +114,11 @@ $ git cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git cvsexportcommit Author ------ -Written by Martin Langhoff <martin@catalyst.net.nz> and others. +Written by Martin Langhoff <martin@laptop.org> and others. Documentation -------------- -Documentation by Martin Langhoff <martin@catalyst.net.nz> and others. +Documentation by Martin Langhoff <martin@laptop.org> and others. GIT --- diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index f4472c6..70cbb2c 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -399,13 +399,13 @@ This program is copyright The Open University UK - 2006. Authors: - Martyn Smith <martyn@catalyst.net.nz> -- Martin Langhoff <martin@catalyst.net.nz> +- Martin Langhoff <martin@laptop.org> with ideas and patches from participants of the git-list <git@vger.kernel.org>. Documentation -------------- -Documentation by Martyn Smith <martyn@catalyst.net.nz>, Martin Langhoff <martin@catalyst.net.nz>, and Matthias Urlichs <smurf@smurf.noris.de>. +Documentation by Martyn Smith <martyn@catalyst.net.nz>, Martin Langhoff <martin@laptop.org>, and Matthias Urlichs <smurf@smurf.noris.de>. GIT --- diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 01c9f8e..d15cb6a 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -9,15 +9,15 @@ SYNOPSIS -------- [verse] 'git daemon' [--verbose] [--syslog] [--export-all] - [--timeout=n] [--init-timeout=n] [--max-connections=n] - [--strict-paths] [--base-path=path] [--base-path-relaxed] - [--user-path | --user-path=path] - [--interpolated-path=pathtemplate] - [--reuseaddr] [--detach] [--pid-file=file] - [--enable=service] [--disable=service] - [--allow-override=service] [--forbid-override=service] - [--inetd | [--listen=host_or_ipaddr] [--port=n] [--user=user [--group=group]] - [directory...] + [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] + [--strict-paths] [--base-path=<path>] [--base-path-relaxed] + [--user-path | --user-path=<path>] + [--interpolated-path=<pathtemplate>] + [--reuseaddr] [--detach] [--pid-file=<file>] + [--enable=<service>] [--disable=<service>] + [--allow-override=<service>] [--forbid-override=<service>] + [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]] + [<directory>...] DESCRIPTION ----------- @@ -48,7 +48,7 @@ OPTIONS 'git daemon' will refuse to start when this option is enabled and no whitelist is specified. ---base-path=path:: +--base-path=<path>:: Remap all the path requests as relative to the given path. This is sort of "GIT root" - if you run 'git daemon' with '--base-path=/srv/git' on example.com, then if you later try to pull @@ -61,7 +61,7 @@ OPTIONS This is useful for switching to --base-path usage, while still allowing the old paths. ---interpolated-path=pathtemplate:: +--interpolated-path=<pathtemplate>:: To support virtual hosting, an interpolated path template can be used to dynamically construct alternate paths. The template supports %H for the target hostname as supplied by the client but @@ -78,29 +78,31 @@ OPTIONS --inetd:: Have the server run as an inetd service. Implies --syslog. - Incompatible with --port, --listen, --user and --group options. + Incompatible with --detach, --port, --listen, --user and --group + options. ---listen=host_or_ipaddr:: +--listen=<host_or_ipaddr>:: Listen on a specific IP address or hostname. IP addresses can be either an IPv4 address or an IPv6 address if supported. If IPv6 is not supported, then --listen=hostname is also not supported and --listen must be given an IPv4 address. + Can be given more than once. Incompatible with '--inetd' option. ---port=n:: +--port=<n>:: Listen on an alternative port. Incompatible with '--inetd' option. ---init-timeout=n:: +--init-timeout=<n>:: Timeout between the moment the connection is established and the client request is received (typically a rather low value, since that should be basically immediate). ---timeout=n:: +--timeout=<n>:: Timeout for specific client sub-requests. This includes the time it takes for the server to process the sub-request and the time spent waiting for the next client's request. ---max-connections=n:: +--max-connections=<n>:: Maximum number of concurrent clients, defaults to 32. Set it to zero for no limit. @@ -109,7 +111,7 @@ OPTIONS --verbose, thus by default only error conditions will be logged. --user-path:: ---user-path=path:: +--user-path=<path>:: Allow {tilde}user notation to be used in requests. When specified with no parameter, requests to git://host/{tilde}alice/foo is taken as a request to access @@ -129,12 +131,12 @@ OPTIONS --detach:: Detach from the shell. Implies --syslog. ---pid-file=file:: +--pid-file=<file>:: Save the process id in 'file'. Ignored when the daemon is run under `--inetd`. ---user=user:: ---group=group:: +--user=<user>:: +--group=<group>:: Change daemon's uid and gid before entering the service loop. When only `--user` is given without `--group`, the primary group ID for the user is used. The values of @@ -145,16 +147,16 @@ Giving these options is an error when used with `--inetd`; use the facility of inet daemon to achieve the same before spawning 'git daemon' if needed. ---enable=service:: ---disable=service:: +--enable=<service>:: +--disable=<service>:: Enable/disable the service site-wide per default. Note that a service disabled site-wide can still be enabled per repository if it is marked overridable and the repository enables the service with a configuration item. ---allow-override=service:: ---forbid-override=service:: +--allow-override=<service>:: +--forbid-override=<service>:: Allow/forbid overriding the site-wide default with per repository configuration. By default, all the services are overridable. diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 7ef9d51..02e015a 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -37,7 +37,7 @@ OPTIONS --all:: Instead of using only the annotated tags, use any ref found in `.git/refs/`. This option enables matching - any known branch, remote branch, or lightweight tag. + any known branch, remote-tracking branch, or lightweight tag. --tags:: Instead of using only the annotated tags, use any tag diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 08fd409..f6ac847 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -8,12 +8,17 @@ git-diff - Show changes between commits, commit and working tree, etc SYNOPSIS -------- -'git diff' [<common diff options>] <commit>{0,2} [--] [<path>...] +[verse] +'git diff' [options] [<commit>] [--] [<path>...] +'git diff' [options] --cached [<commit>] [--] [<path>...] +'git diff' [options] <commit> <commit> [--] [<path>...] +'git diff' [options] [--no-index] [--] <path> <path> DESCRIPTION ----------- -Show changes between two trees, a tree and the working tree, a -tree and the index file, or the index file and the working tree. +Show changes between the working tree and the index or a tree, changes +between the index and a tree, changes between two trees, or changes +between two files on disk. 'git diff' [--options] [--] [<path>...]:: @@ -23,9 +28,9 @@ tree and the index file, or the index file and the working tree. further add to the index but you still haven't. You can stage these changes by using linkgit:git-add[1]. + -If exactly two paths are given, and at least one is untracked, -compare the two files / directories. This behavior can be -forced by --no-index. +If exactly two paths are given and at least one points outside +the current repository, 'git diff' will compare the two files / +directories. This behavior can be forced by --no-index. 'git diff' [--options] --cached [<commit>] [--] [<path>...]:: @@ -64,15 +69,16 @@ forced by --no-index. Just in case if you are doing something exotic, it should be noted that all of the <commit> in the above description, except -for the last two forms that use ".." notations, can be any -<tree-ish>. +in the last two forms that use ".." notations, can be any +<tree>. The third form ('git diff <commit> <commit>') can also +be used to compare two <blob> objects. For a more complete list of ways to spell <commit>, see -"SPECIFYING REVISIONS" section in linkgit:gitrevisions[1]. +"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. However, "diff" is about comparing two _endpoints_, not ranges, and the range notations ("<commit>..<commit>" and "<commit>\...<commit>") do not mean a range as defined in the -"SPECIFYING RANGES" section in linkgit:gitrevisions[1]. +"SPECIFYING RANGES" section in linkgit:gitrevisions[7]. OPTIONS ------- @@ -159,8 +165,12 @@ rewrites (very expensive). SEE ALSO -------- -linkgit:git-difftool[1]:: - Show changes using common diff tools +diff(1), +linkgit:git-difftool[1], +linkgit:git-log[1], +linkgit:gitdiffcore[7], +linkgit:git-format-patch[1], +linkgit:git-apply[1] Author ------ diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 8250bad..6fffbc7 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -7,13 +7,14 @@ git-difftool - Show changes using common diff tools SYNOPSIS -------- -'git difftool' [<options>] <commit>{0,2} [--] [<path>...] +'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...] DESCRIPTION ----------- 'git difftool' is a git command that allows you to compare and edit files between revisions using common diff tools. 'git difftool' is a frontend -to 'git diff' and accepts the same options and arguments. +to 'git diff' and accepts the same options and arguments. See +linkgit:git-diff[1]. OPTIONS ------- diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index fcad113..e05b686 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -96,7 +96,7 @@ marks the same across runs. in the commit (as opposed to just listing the files which are different from the commit's first parent). -[git-rev-list-args...]:: +[<git-rev-list-args>...]:: A list of arguments, acceptable to 'git rev-parse' and 'git rev-list', that specifies the specific objects and references to export. For example, `master{tilde}10..master` causes the diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 966ba4f..5d0c245 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -439,7 +439,7 @@ Marks must be declared (via `mark`) before they can be used. * A complete 40 byte or abbreviated commit SHA-1 in hex. * Any valid Git SHA-1 expression that resolves to a commit. See - ``SPECIFYING REVISIONS'' in linkgit:gitrevisions[1] for details. + ``SPECIFYING REVISIONS'' in linkgit:gitrevisions[7] for details. The special case of restarting an incremental import from the current branch value should be written as: @@ -524,6 +524,9 @@ start with double quote (`"`). If an `LF` or double quote must be encoded into `<path>` shell-style quoting should be used, e.g. `"path/with\n and \" in it"`. +Additionally, in `040000` mode, `<path>` may also be an empty string +(`""`) to specify the root of the tree. + The value of `<path>` must be in canonical form. That is it must not: * contain an empty directory component (e.g. `foo//bar` is invalid), diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 400fe7f..c76e313 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git fetch' [<options>] <group> -'git fetch' --multiple [<options>] [<repository> | <group>]... +'git fetch' --multiple [<options>] [(<repository> | <group>)...] 'git fetch' --all [<options>] @@ -26,7 +26,7 @@ The ref names and their object names of fetched refs are stored in `.git/FETCH_HEAD`. This information is left for a later merge operation done by 'git merge'. -When <refspec> stores the fetched result in tracking branches, +When <refspec> stores the fetched result in remote-tracking branches, the tags that point at these branches are automatically followed. This is done by first fetching from the remote using the given <refspec>s, and if the repository has objects that are diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index f51860d..796e748 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -117,7 +117,7 @@ OPTIONS This is the filter for performing the commit. If this filter is specified, it will be called instead of the 'git commit-tree' command, with arguments of the form - "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on + "<TREE_ID> [(-p <PARENT_COMMIT_ID>)...]" and the log message on stdin. The commit id is expected on stdout. + As a special extension, the commit filter may emit multiple diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 302f56b..40dba8c 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -9,8 +9,8 @@ git-fmt-merge-msg - Produce a merge commit message SYNOPSIS -------- [verse] -'git fmt-merge-msg' [-m <message>] [--log | --no-log] <$GIT_DIR/FETCH_HEAD -'git fmt-merge-msg' [-m <message>] [--log | --no-log] -F <file> +'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] <$GIT_DIR/FETCH_HEAD +'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] -F <file> DESCRIPTION ----------- @@ -24,10 +24,12 @@ automatically invoking 'git merge'. OPTIONS ------- ---log:: +--log[=<n>]:: In addition to branch names, populate the log message with one-line descriptions from the actual commits that are being - merged. + merged. At most <n> commits from each merge parent will be + used (20 if <n> is omitted). This overrides the `merge.log` + configuration variable. --no-log:: Do not list one-line descriptions from the actual commits being @@ -52,8 +54,10 @@ CONFIGURATION ------------- merge.log:: - Whether to include summaries of merged commits in newly - merge commit messages. False by default. + In addition to branch names, populate the log message with at + most the specified number of one-line descriptions from the + actual commits that are being merged. Defaults to false, and + true is a synoym for 20. merge.summary:: Synonym to `merge.log`; this is deprecated and will be removed in diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index d66fd9d..fac1cf5 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] - [--sort=<key>]* [--format=<format>] [<pattern>...] + [(--sort=<key>)...] [--format=<format>] [<pattern>...] DESCRIPTION ----------- diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 4b3f5ba..9dcafc6 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -39,7 +39,7 @@ There are two ways to specify which commits to operate on. that leads to the <since> to be output. 2. Generic <revision range> expression (see "SPECIFYING - REVISIONS" section in linkgit:gitrevisions[1]) means the + REVISIONS" section in linkgit:gitrevisions[7]) means the commits in the specified range. The first rule takes precedence in the case of a single <commit>. To @@ -74,7 +74,7 @@ OPTIONS include::diff-options.txt[] -<n>:: - Limits the number of patches to prepare. + Prepare patches from the topmost <n> commits. -o <dir>:: --output-directory <dir>:: diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 315f07e..801aede 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -89,7 +89,7 @@ are not part of the current project most users will want to expire them sooner. This option defaults to '30 days'. The above two configuration variables can be given to a pattern. For -example, this sets non-default expiry values only to remote tracking +example, this sets non-default expiry values only to remote-tracking branches: ------------ @@ -128,8 +128,8 @@ Notes 'git gc' tries very hard to be safe about the garbage it collects. In particular, it will keep not only objects referenced by your current set -of branches and tags, but also objects referenced by the index, remote -tracking branches, refs saved by 'git filter-branch' in +of branches and tags, but also objects referenced by the index, +remote-tracking branches, refs saved by 'git filter-branch' in refs/original/, or reflogs (which may reference commits in branches that were later amended or rewound). diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index f3ccc72..c2bb810 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -59,10 +59,10 @@ OPTIONS the newly constructed pack and index before refs can be updated to use objects contained in the pack. ---keep='why':: +--keep=<msg>:: Like --keep create a .keep file before moving the index into its final destination, but rather than creating an empty file - place 'why' followed by an LF into the .keep file. The 'why' + place '<msg>' followed by an LF into the .keep file. The '<msg>' message can later be searched for within all .keep files to locate any which have outlived their usefulness. diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 246b07e..00d4a12 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -31,7 +31,7 @@ current working directory. Specify the directory from which templates will be used. (See the "TEMPLATE DIRECTORY" section below.) ---shared[={false|true|umask|group|all|world|everybody|0xxx}]:: +--shared[=(false|true|umask|group|all|world|everybody|0xxx)]:: Specify that the git repository is to be shared amongst several users. This allows users belonging to the same group to push into that diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index c213bdb..ff41784 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -31,7 +31,7 @@ OPTIONS either <since> or <until> is omitted, it defaults to `HEAD`, i.e. the tip of the current branch. For a more complete list of ways to spell <since> - and <until>, see linkgit:gitrevisions[1]. + and <until>, see linkgit:gitrevisions[7]. --follow:: Continue listing the history of a file beyond renames @@ -116,7 +116,7 @@ git log --follow builtin-rev-list.c:: git log --branches --not --remotes=origin:: Shows all commits that are in any of local branches but not in - any of remote tracking branches for 'origin' (what you have that + any of remote-tracking branches for 'origin' (what you have that origin doesn't). git log master --not --remotes=*/master:: diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 347f447..86abd13 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -17,7 +17,7 @@ SYNOPSIS [--exclude-per-directory=<file>] [--exclude-standard] [--error-unmatch] [--with-tree=<tree-ish>] - [--full-name] [--abbrev] [--] [<file>]* + [--full-name] [--abbrev] [--] [<file>...] DESCRIPTION ----------- diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 1f89d36..76ed625 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -10,8 +10,8 @@ SYNOPSIS -------- [verse] 'git ls-tree' [-d] [-r] [-t] [-l] [-z] - [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev=[<n>]] - <tree-ish> [paths...] + [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]] + <tree-ish> [<path>...] DESCRIPTION ----------- @@ -19,11 +19,11 @@ Lists the contents of a given tree object, like what "/bin/ls -a" does in the current working directory. Note that: - the behaviour is slightly different from that of "/bin/ls" in that the - 'paths' denote just a list of patterns to match, e.g. so specifying + '<path>' denotes just a list of patterns to match, e.g. so specifying directory name (without '-r') will behave differently, and order of the arguments does not matter. - - the behaviour is similar to that of "/bin/ls" in that the 'paths' is + - the behaviour is similar to that of "/bin/ls" in that the '<path>' is taken as relative to the current working directory. E.g. when you are in a directory 'sub' that has a directory 'dir', you can run 'git ls-tree -r HEAD dir' to list the contents of the tree (that is @@ -72,7 +72,7 @@ OPTIONS Do not limit the listing to the current working directory. Implies --full-name. -paths:: +[<path>...]:: When paths are given, show them (note that this isn't really raw pathnames, but rather a list of patterns to match). Otherwise implicitly uses the root level of the tree as the sole path argument. diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index a634485..71912a1 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -7,7 +7,7 @@ git-mailsplit - Simple UNIX mbox splitter program SYNOPSIS -------- -'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [<mbox>|<Maildir>...] +'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [(<mbox>|<Maildir>)...] DESCRIPTION ----------- diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 84043cc..c1efaaa 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -13,6 +13,7 @@ SYNOPSIS [-s <strategy>] [-X <strategy-option>] [--[no-]rerere-autoupdate] [-m <msg>] <commit>... 'git merge' <msg> HEAD <commit>... +'git merge' --abort DESCRIPTION ----------- @@ -47,6 +48,14 @@ The second syntax (<msg> `HEAD` <commit>...) is supported for historical reasons. Do not use it from the command line or in new scripts. It is the same as `git merge -m <msg> <commit>...`. +The third syntax ("`git merge --abort`") can only be run after the +merge has resulted in conflicts. 'git merge --abort' will abort the +merge process and try to reconstruct the pre-merge state. However, +if there were uncommitted changes when the merge started (and +especially if those changes were further modified after the merge +was started), 'git merge --abort' will in some cases be unable to +reconstruct the original (pre-merge) changes. Therefore: + *Warning*: Running 'git merge' with uncommitted changes is discouraged: while possible, it leaves you in a state that is hard to back out of in the case of a conflict. @@ -59,19 +68,31 @@ include::merge-options.txt[] -m <msg>:: Set the commit message to be used for the merge commit (in case one is created). - - If `--log` is specified, a shortlog of the commits being merged - will be appended to the specified message. - - The 'git fmt-merge-msg' command can be - used to give a good default for automated 'git merge' - invocations. ++ +If `--log` is specified, a shortlog of the commits being merged +will be appended to the specified message. ++ +The 'git fmt-merge-msg' command can be +used to give a good default for automated 'git merge' +invocations. --rerere-autoupdate:: --no-rerere-autoupdate:: Allow the rerere mechanism to update the index with the result of auto-conflict resolution if possible. +--abort:: + Abort the current conflict resolution process, and + try to reconstruct the pre-merge state. ++ +If there were uncommitted worktree changes present when the merge +started, 'git merge --abort' will in some cases be unable to +reconstruct these changes. It is therefore recommended to always +commit or stash your changes before running 'git merge'. ++ +'git merge --abort' is equivalent to 'git reset --merge' when +`MERGE_HEAD` is present. + <commit>...:: Commits, usually other branch heads, to merge into our branch. You need at least one <commit>. Specifying more than one @@ -142,7 +163,7 @@ happens: i.e. matching `HEAD`. If you tried a merge which resulted in complex conflicts and -want to start over, you can recover with `git reset --merge`. +want to start over, you can recover with `git merge --abort`. HOW CONFLICTS ARE PRESENTED --------------------------- @@ -213,8 +234,8 @@ After seeing a conflict, you can do two things: * Decide not to merge. The only clean-ups you need are to reset the index file to the `HEAD` commit to reverse 2. and to clean - up working tree changes made by 2. and 3.; `git-reset --hard` can - be used for this. + up working tree changes made by 2. and 3.; `git merge --abort` + can be used for this. * Resolve the conflicts. Git will mark the conflicts in the working tree. Edit the files into shape and diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index e4ed016..1f75a84 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -7,7 +7,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts SYNOPSIS -------- -'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>]... +'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...] DESCRIPTION ----------- diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 2981d8c..296f314 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -14,8 +14,12 @@ SYNOPSIS 'git notes' append [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] 'git notes' edit [<object>] 'git notes' show [<object>] +'git notes' merge [-v | -q] [-s <strategy> ] <notes_ref> +'git notes' merge --commit [-v | -q] +'git notes' merge --abort [-v | -q] 'git notes' remove [<object>] 'git notes' prune [-n | -v] +'git notes' get-ref DESCRIPTION @@ -83,6 +87,21 @@ edit:: show:: Show the notes for a given object (defaults to HEAD). +merge:: + Merge the given notes ref into the current notes ref. + This will try to merge the changes made by the given + notes ref (called "remote") since the merge-base (if + any) into the current notes ref (called "local"). ++ +If conflicts arise and a strategy for automatically resolving +conflicting notes (see the -s/--strategy option) is not given, +the "manual" resolver is used. This resolver checks out the +conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`), +and instructs the user to manually resolve the conflicts there. +When done, the user can either finalize the merge with +'git notes merge --commit', or abort the merge with +'git notes merge --abort'. + remove:: Remove the notes for a given object (defaults to HEAD). This is equivalent to specifying an empty note message to @@ -91,6 +110,10 @@ remove:: prune:: Remove all notes for non-existing/unreachable objects. +get-ref:: + Print the current notes ref. This provides an easy way to + retrieve the current notes ref (e.g. from scripts). + OPTIONS ------- -f:: @@ -133,9 +156,37 @@ OPTIONS Do not remove anything; just report the object names whose notes would be removed. +-s <strategy>:: +--strategy=<strategy>:: + When merging notes, resolve notes conflicts using the given + strategy. The following strategies are recognized: "manual" + (default), "ours", "theirs", "union" and "cat_sort_uniq". + See the "NOTES MERGE STRATEGIES" section below for more + information on each notes merge strategy. + +--commit:: + Finalize an in-progress 'git notes merge'. Use this option + when you have resolved the conflicts that 'git notes merge' + stored in .git/NOTES_MERGE_WORKTREE. This amends the partial + merge commit created by 'git notes merge' (stored in + .git/NOTES_MERGE_PARTIAL) by adding the notes in + .git/NOTES_MERGE_WORKTREE. The notes ref stored in the + .git/NOTES_MERGE_REF symref is updated to the resulting commit. + +--abort:: + Abort/reset a in-progress 'git notes merge', i.e. a notes merge + with conflicts. This simply removes all files related to the + notes merge. + +-q:: +--quiet:: + When merging notes, operate quietly. + -v:: --verbose:: - Report all object names whose notes are removed. + When merging notes, be more verbose. + When pruning notes, report all object names whose notes are + removed. DISCUSSION @@ -163,6 +214,38 @@ object, in which case the history of the notes can be read with `git log -p -g <refname>`. +NOTES MERGE STRATEGIES +---------------------- + +The default notes merge strategy is "manual", which checks out +conflicting notes in a special work tree for resolving notes conflicts +(`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the +conflicts in that work tree. +When done, the user can either finalize the merge with +'git notes merge --commit', or abort the merge with +'git notes merge --abort'. + +"ours" automatically resolves conflicting notes in favor of the local +version (i.e. the current notes ref). + +"theirs" automatically resolves notes conflicts in favor of the remote +version (i.e. the given notes ref being merged into the current notes +ref). + +"union" automatically resolves notes conflicts by concatenating the +local and remote versions. + +"cat_sort_uniq" is similar to "union", but in addition to concatenating +the local and remote versions, this strategy also sorts the resulting +lines, and removes duplicate lines from the result. This is equivalent +to applying the "cat | sort | uniq" shell pipeline to the local and +remote versions. This strategy is useful if the notes follow a line-based +format where one wants to avoid duplicated lines in the merge result. +Note that if either the local or remote version contain duplicate lines +prior to the merge, these will also be removed by this notes merge +strategy. + + EXAMPLES -------- diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 8ed09c0..65eff66 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -11,8 +11,8 @@ SYNOPSIS [verse] 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied] [--no-reuse-delta] [--delta-base-offset] [--non-empty] - [--local] [--incremental] [--window=N] [--depth=N] - [--revs [--unpacked | --all]*] [--stdout | base-name] + [--local] [--incremental] [--window=<n>] [--depth=<n>] + [--revs [--unpacked | --all]] [--stdout | base-name] [--keep-true-parents] < object-list @@ -82,8 +82,8 @@ base-name:: reference was included in the resulting packfile. This can be useful to send new tags to native git clients. ---window=[N]:: ---depth=[N]:: +--window=<n>:: +--depth=<n>:: These two options affect how the objects contained in the pack are stored using delta compression. The objects are first internally sorted by type, size and @@ -95,10 +95,10 @@ base-name:: times to get to the necessary object. The default value for --window is 10 and --depth is 50. ---window-memory=[N]:: +--window-memory=<n>:: This option provides an additional limit on top of `--window`; the window size will dynamically scale down so as to not take - up more than N bytes in memory. This is useful in + up more than '<n>' bytes in memory. This is useful in repositories with a mix of large and small objects to not run out of memory with a large window, but still be able to take advantage of the large window for the smaller objects. The @@ -106,7 +106,7 @@ base-name:: `--window-memory=0` makes memory usage unlimited, which is the default. ---max-pack-size=[N]:: +--max-pack-size=<n>:: Maximum size of each output pack file. The size can be suffixed with "k", "m", or "g". The minimum size allowed is limited to 1 MiB. If specified, multiple packfiles may be created. @@ -171,7 +171,7 @@ base-name:: wholesale enforcement of a different compression level on the packed data is desired. ---compression=[N]:: +--compression=<n>:: Specifies compression level for newly-compressed data in the generated pack. If not specified, pack compression level is determined first by pack.compression, then by core.compression, diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index c50f7dc..4db7373 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -26,9 +26,9 @@ With `--rebase`, it runs 'git rebase' instead of 'git merge'. <repository> should be the name of a remote repository as passed to linkgit:git-fetch[1]. <refspec> can name an arbitrary remote ref (for example, the name of a tag) or even -a collection of refs with corresponding remote tracking branches -(e.g., refs/heads/*:refs/remotes/origin/*), but usually it is -the name of a branch in the remote repository. +a collection of refs with corresponding remote-tracking branches +(e.g., refs/heads/{asterisk}:refs/remotes/origin/{asterisk}), +but usually it is the name of a branch in the remote repository. Default values for <repository> and <branch> are read from the "remote" and "merge" configuration for the current branch @@ -92,12 +92,14 @@ include::merge-options.txt[] :git-pull: 1 --rebase:: - Instead of a merge, perform a rebase after fetching. If - there is a remote ref for the upstream branch, and this branch - was rebased since last fetched, the rebase uses that information - to avoid rebasing non-local changes. To make this the default - for branch `<name>`, set configuration `branch.<name>.rebase` - to `true`. + Rebase the current branch on top of the upstream branch after + fetching. If there is a remote-tracking branch corresponding to + the upstream branch and the upstream branch was rebased since last + fetched, the rebase uses that information to avoid rebasing + non-local changes. ++ +See `branch.<name>.rebase` in linkgit:git-config[1] if you want to make +`git pull` always use `{litdd}rebase` instead of merging. + [NOTE] This is a potentially _dangerous_ mode of operation. @@ -134,7 +136,7 @@ and if there is not any such variable, the value on `URL: ` line in `$GIT_DIR/remotes/<origin>` file is used. In order to determine what remote branches to fetch (and -optionally store in the tracking branches) when the command is +optionally store in the remote-tracking branches) when the command is run without any refspec parameters on the command line, values of the configuration variable `remote.<origin>.fetch` are consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>` @@ -147,9 +149,9 @@ refs/heads/*:refs/remotes/origin/* ------------ A globbing refspec must have a non-empty RHS (i.e. must store -what were fetched in tracking branches), and its LHS and RHS +what were fetched in remote-tracking branches), and its LHS and RHS must end with `/*`. The above specifies that all remote -branches are tracked using tracking branches in +branches are tracked using remote-tracking branches in `refs/remotes/origin/` hierarchy under the same name. The rule to determine which remote branch to merge after diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 020955f..e11660a 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -41,7 +41,7 @@ OPTIONS[[OPTIONS]] + The <src> is often the name of the branch you would want to push, but it can be any arbitrary "SHA-1 expression", such as `master~4` or -`HEAD` (see linkgit:gitrevisions[1]). +`HEAD` (see linkgit:gitrevisions[7]). + The <dst> tells which ref on the remote side is updated with this push. Arbitrary expressions cannot be used here, an actual ref must diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 2e78da4..e88e9c2 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -11,7 +11,7 @@ SYNOPSIS 'git read-tree' [[-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>] [-u [--exclude-per-directory=<gitignore>] | -i]] [--index-output=<file>] [--no-sparse-checkout] - <tree-ish1> [<tree-ish2> [<tree-ish3>]] + (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]]) DESCRIPTION @@ -114,6 +114,10 @@ OPTIONS Disable sparse checkout support even if `core.sparseCheckout` is true. +--empty:: + Instead of reading tree object(s) into the index, just empty + it. + <tree-ish#>:: The id of the tree object(s) to be read/merged. diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index 5a0451a..e50bd9b 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -40,7 +40,7 @@ see linkgit:git-log[1]. The reflog is useful in various git commands, to specify the old value of a reference. For example, `HEAD@\{2\}` means "where HEAD used to be two moves ago", `master@\{one.week.ago\}` means "where master used to -point to one week ago", and so on. See linkgit:gitrevisions[1] for +point to one week ago", and so on. See linkgit:gitrevisions[7] for more details. To delete single entries from the reflog, use the subcommand "delete" diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt index 8a5842b..8fc809f 100644 --- a/Documentation/git-relink.txt +++ b/Documentation/git-relink.txt @@ -7,7 +7,7 @@ git-relink - Hardlink common objects in local repositories SYNOPSIS -------- -'git relink' [--safe] <dir> [<dir>]* <master_dir> +'git relink' [--safe] <dir>... <master_dir> DESCRIPTION ----------- diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt new file mode 100644 index 0000000..f4fbf67 --- /dev/null +++ b/Documentation/git-remote-ext.txt @@ -0,0 +1,125 @@ +git-remote-ext(1) +================= + +NAME +---- +git-remote-ext - Bridge smart transport to external command. + +SYNOPSIS +-------- +git remote add nick "ext::<command>[ <arguments>...]" + +DESCRIPTION +----------- +This remote helper uses the specified 'program' to connect +to a remote git server. + +Data written to stdin of this specified 'program' is assumed +to be sent to git:// server, git-upload-pack, git-receive-pack +or git-upload-archive (depending on situation), and data read +from stdout of this program is assumed to be received from +the same service. + +Command and arguments are separated by unescaped space. + +The following sequences have a special meaning: + +'% ':: + Literal space in command or argument. + +'%%':: + Literal percent sign. + +'%s':: + Replaced with name (receive-pack, upload-pack, or + upload-archive) of the service git wants to invoke. + +'%S':: + Replaced with long name (git-receive-pack, + git-upload-pack, or git-upload-archive) of the service + git wants to invoke. + +'%G' (must be first characters in argument):: + This argument will not be passed to 'program'. Instead, it + will cause helper to start by sending git:// service request to + remote side with service field set to approiate value and + repository field set to rest of the argument. Default is not to send + such request. ++ +This is useful if remote side is git:// server accessed over +some tunnel. + +'%V' (must be first characters in argument):: + This argument will not be passed to 'program'. Instead it sets + the vhost field in git:// service request (to rest of the argument). + Default is not to send vhost in such request (if sent). + +ENVIRONMENT VARIABLES: +---------------------- + +GIT_TRANSLOOP_DEBUG:: + If set, prints debugging information about various reads/writes. + +ENVIRONMENT VARIABLES PASSED TO COMMAND: +---------------------------------------- + +GIT_EXT_SERVICE:: + Set to long name (git-upload-pack, etc...) of service helper needs + to invoke. + +GIT_EXT_SERVICE_NOPREFIX:: + Set to long name (upload-pack, etc...) of service helper needs + to invoke. + + +EXAMPLES: +--------- +This remote helper is transparently used by git when +you use commands such as "git fetch <URL>", "git clone <URL>", +, "git push <URL>" or "git remote add nick <URL>", where <URL> +begins with `ext::`. Examples: + +"ext::ssh -i /home/foo/.ssh/somekey user@host.example %S 'foo/repo'":: + Like host.example:foo/repo, but use /home/foo/.ssh/somekey as + keypair and user as user on remote side. This avoids needing to + edit .ssh/config. + +"ext::socat -t3600 - ABSTRACT-CONNECT:/git-server %G/somerepo":: + Represents repository with path /somerepo accessable over + git protocol at abstract namespace address /git-server. + +"ext::git-server-alias foo %G/repo":: + Represents a repository with path /repo accessed using the + helper program "git-server-alias foo". The path to the + repository and type of request are not passed on the command + line but as part of the protocol stream, as usual with git:// + protocol. + +"ext::git-server-alias foo %G/repo %Vfoo":: + Represents a repository with path /repo accessed using the + helper program "git-server-alias foo". The hostname for the + remote server passed in the protocol stream will be "foo" + (this allows multiple virtual git servers to share a + link-level address). + +"ext::git-server-alias foo %G/repo% with% spaces %Vfoo":: + Represents a repository with path '/repo with spaces' accessed + using the helper program "git-server-alias foo". The hostname for + the remote server passed in the protocol stream will be "foo" + (this allows multiple virtual git servers to share a + link-level address). + +"ext::git-ssl foo.example /bar":: + Represents a repository accessed using the helper program + "git-ssl foo.example /bar". The type of request can be + determined by the helper using environment variables (see + above). + +Documentation +-------------- +Documentation by Ilari Liusvaara, Jonathan Nieder and the git list +<git@vger.kernel.org> + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt new file mode 100644 index 0000000..abc4944 --- /dev/null +++ b/Documentation/git-remote-fd.txt @@ -0,0 +1,59 @@ +git-remote-fd(1) +================ + +NAME +---- +git-remote-fd - Reflect smart transport stream back to caller + +SYNOPSIS +-------- +"fd::<infd>[,<outfd>][/<anything>]" (as URL) + +DESCRIPTION +----------- +This helper uses specified file descriptors to connect to remote git server. +This is not meant for end users but for programs and scripts calling git +fetch, push or archive. + +If only <infd> is given, it is assumed to be bidirectional socket connected +to remote git server (git-upload-pack, git-receive-pack or +git-upload-achive). If both <infd> and <outfd> are given, they are assumed +to be pipes connected to remote git server (<infd> being the inbound pipe +and <outfd> being the outbound pipe. + +It is assumed that any handshaking procedures have already been completed +(such as sending service request for git://) before this helper is started. + +<anything> can be any string. It is ignored. It is meant for provoding +information to user in the URL in case that URL is displayed in some +context. + +ENVIRONMENT VARIABLES +--------------------- +GIT_TRANSLOOP_DEBUG:: + If set, prints debugging information about various reads/writes. + +EXAMPLES +-------- +git fetch fd::17 master:: + Fetch master, using file descriptor #17 to communicate with + git-upload-pack. + +git fetch fd::17/foo master:: + Same as above. + +git push fd::7,8 master (as URL):: + Push master, using file descriptor #7 to read data from + git-receive-pack and file descriptor #8 to write data to + same service. + +git push fd::7,8/bar master:: + Same as above. + +Documentation +-------------- +Documentation by Ilari Liusvaara and the git list <git@vger.kernel.org> + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index aa021b0..c258ea4 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -20,7 +20,7 @@ SYNOPSIS 'git remote set-url --delete' [--push] <name> <url> 'git remote' [-v | --verbose] 'show' [-n] <name> 'git remote prune' [-n | --dry-run] <name> -'git remote' [-v | --verbose] 'update' [-p | --prune] [group | remote]... +'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...] DESCRIPTION ----------- @@ -75,7 +75,7 @@ was passed. 'rename':: -Rename the remote named <old> to <new>. All remote tracking branches and +Rename the remote named <old> to <new>. All remote-tracking branches and configuration settings for the remote are updated. + In case <old> and <new> are the same, and <old> is a file under @@ -84,7 +84,7 @@ the configuration file format. 'rm':: -Remove the remote named <name>. All remote tracking branches and +Remove the remote named <name>. All remote-tracking branches and configuration settings for the remote are removed. 'set-head':: @@ -146,7 +146,7 @@ With `-n` option, the remote heads are not queried first with 'prune':: -Deletes all stale tracking branches under <name>. +Deletes all stale remote-tracking branches under <name>. These stale branches have already been removed from the remote repository referenced by <name>, but are still locally available in "remotes/<name>". diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 8c67d17..27f7865 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -8,7 +8,7 @@ git-repack - Pack unpacked objects in a repository SYNOPSIS -------- -'git repack' [-a] [-A] [-d] [-f] [-l] [-n] [-q] [--window=N] [--depth=N] +'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=<n>] [--depth=<n>] DESCRIPTION ----------- @@ -62,6 +62,10 @@ other objects in that pack they already have locally. linkgit:git-pack-objects[1]. -f:: + Pass the `--no-reuse-delta` option to `git-pack-objects`, see + linkgit:git-pack-objects[1]. + +-F:: Pass the `--no-reuse-object` option to `git-pack-objects`, see linkgit:git-pack-objects[1]. @@ -76,8 +80,8 @@ other objects in that pack they already have locally. this repository (or a direct copy of it) over HTTP or FTP. See linkgit:git-update-server-info[1]. ---window=[N]:: ---depth=[N]:: +--window=<n>:: +--depth=<n>:: These two options affect how the objects contained in the pack are stored using delta compression. The objects are first internally sorted by type, size and optionally names and compared against the @@ -87,10 +91,10 @@ other objects in that pack they already have locally. to be applied that many times to get to the necessary object. The default value for --window is 10 and --depth is 50. ---window-memory=[N]:: +--window-memory=<n>:: This option provides an additional limit on top of `--window`; the window size will dynamically scale down so as to not take - up more than N bytes in memory. This is useful in + up more than '<n>' bytes in memory. This is useful in repositories with a mix of large and small objects to not run out of memory with a large window, but still be able to take advantage of the large window for the smaller objects. The @@ -98,7 +102,7 @@ other objects in that pack they already have locally. `--window-memory=0` makes memory usage unlimited, which is the default. ---max-pack-size=[N]:: +--max-pack-size=<n>:: Maximum size of each output pack file. The size can be suffixed with "k", "m", or "g". The minimum size allowed is limited to 1 MiB. If specified, multiple packfiles may be created. diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 9cf3148..fd72976 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -15,17 +15,24 @@ SYNOPSIS DESCRIPTION ----------- In the first and second form, copy entries from <commit> to the index. -In the third form, set the current branch to <commit>, optionally -modifying index and worktree to match. The <commit> defaults to HEAD +In the third form, set the current branch head (HEAD) to <commit>, optionally +modifying index and working tree to match. The <commit> defaults to HEAD in all forms. 'git reset' [-q] [<commit>] [--] <paths>...:: This form resets the index entries for all <paths> to their - state at the <commit>. (It does not affect the worktree, nor + state at <commit>. (It does not affect the working tree, nor the current branch.) + This means that `git reset <paths>` is the opposite of `git add <paths>`. ++ +After running `git reset <paths>` to update the index entry, you can +use linkgit:git-checkout[1] to check the contents out of the index to +the working tree. +Alternatively, using linkgit:git-checkout[1] and specifying a commit, you +can copy the contents of a path out of a commit to the index and to the +working tree in one go. 'git reset' --patch|-p [<commit>] [--] [<paths>...]:: Interactively select hunks in the difference between the index @@ -36,16 +43,17 @@ This means that `git reset -p` is the opposite of `git add -p` (see linkgit:git-add[1]). 'git reset' [--<mode>] [<commit>]:: - This form points the current branch to <commit> and then - updates index and working tree according to <mode>, which must - be one of the following: + This form resets the current branch head to <commit> and + possibly updates the index (resetting it to the tree of <commit>) and + the working tree depending on <mode>, which + must be one of the following: + -- --soft:: - Does not touch the index file nor the working tree at all, but - requires them to be in a good order. This leaves all your changed - files "Changes to be committed", as 'git status' would - put it. + Does not touch the index file nor the working tree at all (but + resets the head to <commit>, just like all modes do). This leaves + all your changed files "Changes to be committed", as 'git status' + would put it. --mixed:: Resets the index but not the working tree (i.e., the changed files @@ -53,22 +61,30 @@ linkgit:git-add[1]). been updated. This is the default action. --hard:: - Matches the working tree and index to that of the tree being - switched to. Any changes to tracked files in the working tree - since <commit> are lost. + Resets the index and working tree. Any changes to tracked files in the + working tree since <commit> are discarded. --merge:: - Resets the index to match the tree recorded by the named commit, - and updates the files that are different between the named commit - and the current commit in the working tree. + Resets the index and updates the files in the working tree that are + different between <commit> and HEAD, but keeps those which are + different between the index and working tree (i.e. which have changes + which have not been added). + If a file that is different between <commit> and the index has unstaged + changes, reset is aborted. ++ +In other words, --merge does something like a 'git read-tree -u -m <commit>', +but carries forward unmerged index entries. --keep:: - Reset the index to the given commit, keeping local changes in - the working tree since the current commit, while updating - working tree files without local changes to what appears in - the given commit. If a file that is different between the - current commit and the given commit has local changes, reset - is aborted. + Resets the index, updates files in the working tree that are + different between <commit> and HEAD, but keeps those + which are different between HEAD and the working tree (i.e. + which have local changes). + If a file that is different between <commit> and HEAD has local changes, + reset is aborted. ++ +In other words, --keep does a 2-way merge between <commit> and HEAD followed by +'git reset --mixed <commit>'. -- If you want to undo a commit other than the latest on a branch, @@ -184,7 +200,7 @@ tip of the current branch in ORIG_HEAD, so resetting hard to it brings your index file and the working tree back to that state, and resets the tip of the branch to that commit. -Undo a merge or pull inside a dirty work tree:: +Undo a merge or pull inside a dirty working tree:: + ------------ $ git pull <1> @@ -257,7 +273,7 @@ Suppose you are working on something and you commit it, and then you continue working a bit more, but now you think that what you have in your working tree should be in another branch that has nothing to do with what you committed previously. You can start a new branch and -reset it while keeping the changes in your work tree. +reset it while keeping the changes in your working tree. + ------------ $ git tag start @@ -294,8 +310,10 @@ In these tables, A, B, C and D are some different states of a file. For example, the first line of the first table means that if a file is in state A in the working tree, in state B in the index, in state C in HEAD and in state D in the target, then "git reset --soft -target" will put the file in state A in the working tree, in state B -in the index and in state D in HEAD. +target" will leave the file in the working tree in state A and in the +index in state B. It resets (i.e. moves) the HEAD (i.e. the tip of +the current branch, if you are on one) to "target" (which has the file +in state D). working index HEAD target working index HEAD ---------------------------------------------------- @@ -346,11 +364,11 @@ in the index and in state D in HEAD. --keep B C C "reset --merge" is meant to be used when resetting out of a conflicted -merge. Any mergy operation guarantees that the work tree file that is +merge. Any mergy operation guarantees that the working tree file that is involved in the merge does not have local change wrt the index before -it starts, and that it writes the result out to the work tree. So if +it starts, and that it writes the result out to the working tree. So if we see some difference between the index and the target and also -between the index and the work tree, then it means that we are not +between the index and the working tree, then it means that we are not resetting out from a state that a mergy operation left after failing with a conflict. That is why we disallow --merge option in this case. diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 173f3fc..8e1e329 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -9,10 +9,10 @@ git-rev-list - Lists commit objects in reverse chronological order SYNOPSIS -------- [verse] -'git rev-list' [ \--max-count=number ] - [ \--skip=number ] - [ \--max-age=timestamp ] - [ \--min-age=timestamp ] +'git rev-list' [ \--max-count=<number> ] + [ \--skip=<number> ] + [ \--max-age=<timestamp> ] + [ \--min-age=<timestamp> ] [ \--sparse ] [ \--merges ] [ \--no-merges ] @@ -21,10 +21,10 @@ SYNOPSIS [ \--full-history ] [ \--not ] [ \--all ] - [ \--branches[=pattern] ] - [ \--tags[=pattern] ] - [ \--remotes[=pattern] ] - [ \--glob=glob-pattern ] + [ \--branches[=<pattern>] ] + [ \--tags[=<pattern>] ] + [ \--remotes[=<pattern>] ] + [ \--glob=<glob-pattern> ] [ \--stdin ] [ \--quiet ] [ \--topo-order ] @@ -37,7 +37,7 @@ SYNOPSIS [ \--regexp-ignore-case | -i ] [ \--extended-regexp | -E ] [ \--fixed-strings | -F ] - [ \--date={local|relative|default|iso|rfc|short} ] + [ \--date=(local|relative|default|iso|rfc|short) ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] [ \--bisect ] diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 341ca90..4a27643 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -95,7 +95,7 @@ OPTIONS unfortunately named tag "master"), and show them as full refnames (e.g. "refs/heads/master"). ---abbrev-ref[={strict|loose}]:: +--abbrev-ref[=(strict|loose)]:: A non-ambiguous short name of the objects name. The option core.warnAmbiguousRefs is used to select the strict abbreviation mode. diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index b7d9ef7..752fc88 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -31,7 +31,7 @@ OPTIONS <commit>...:: Commits to revert. For a more complete list of ways to spell commit names, see - linkgit:gitrevisions[1]. + linkgit:gitrevisions[7]. Sets of commits can also be given but no traversal is done by default, see linkgit:git-rev-list[1] and its '--no-walk' option. @@ -87,7 +87,7 @@ git revert HEAD~3:: Revert the changes specified by the fourth last commit in HEAD and create a new commit with the reverted changes. -git revert -n master\~5..master~2:: +git revert -n master{tilde}5..master{tilde}2:: Revert the changes done by commits from the fifth last commit in master (included) to the third last commit in master diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 71e3d9f..0adbe8b 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -89,8 +89,8 @@ the paths that have disappeared from the filesystem. However, depending on the use case, there are several ways that can be done. -Using "git commit -a" -~~~~~~~~~~~~~~~~~~~~~ +Using ``git commit -a'' +~~~~~~~~~~~~~~~~~~~~~~~ If you intend that your next commit should record all modifications of tracked files in the working tree and record all removals of files that have been removed from the working tree with `rm` @@ -98,8 +98,8 @@ files that have been removed from the working tree with `rm` automatically notice and record all removals. You can also have a similar effect without committing by using `git add -u`. -Using "git add -A" -~~~~~~~~~~~~~~~~~~ +Using ``git add -A'' +~~~~~~~~~~~~~~~~~~~~ When accepting a new code drop for a vendor branch, you probably want to record both the removal of paths and additions of new paths as well as modifications of existing paths. @@ -111,8 +111,8 @@ tree using this command: git ls-files -z | xargs -0 rm -f ---------------- -and then "untar" the new code in the working tree. Alternately -you could "rsync" the changes into the working tree. +and then untar the new code in the working tree. Alternately +you could 'rsync' the changes into the working tree. After that, the easiest way to record all removals, additions, and modifications in the working tree is: diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index c283084..7ec9dab 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -82,11 +82,26 @@ See the CONFIGURATION section for 'sendemail.multiedit'. set, as returned by "git var -l". --in-reply-to=<identifier>:: - Specify the contents of the first In-Reply-To header. - Subsequent emails will refer to the previous email - instead of this if --chain-reply-to is set. - Only necessary if --compose is also set. If --compose - is not set, this will be prompted for. + Make the first mail (or all the mails with `--no-thread`) appear as a + reply to the given Message-Id, which avoids breaking threads to + provide a new patch series. + The second and subsequent emails will be sent as replies according to + the `--[no]-chain-reply-to` setting. ++ +So for example when `--thread` and `--no-chain-reply-to` are specified, the +second and subsequent patches will be replies to the first one like in the +illustration below where `[PATCH v2 0/3]` is in reply to `[PATCH 0/2]`: ++ + [PATCH 0/2] Here is what I did... + [PATCH 1/2] Clean up and tests + [PATCH 2/2] Implementation + [PATCH v2 0/3] Here is a reroll + [PATCH v2 1/3] Clean up + [PATCH v2 2/3] New tests + [PATCH v2 3/3] Implementation ++ +Only necessary if --compose is also set. If --compose +is not set, this will be prompted for. --subject=<string>:: Specify the initial subject of the email thread. @@ -97,7 +112,7 @@ See the CONFIGURATION section for 'sendemail.multiedit'. Specify the primary recipient of the emails generated. Generally, this will be the upstream maintainer of the project involved. Default is the value of the 'sendemail.to' configuration value; if that is unspecified, - this will be prompted for. + and --to-cmd is not specified, this will be prompted for. + The --to option must be repeated for each user you want on the to list. @@ -165,6 +180,15 @@ user is prompted for a password while the input is masked for privacy. are also accepted. The port can also be set with the 'sendemail.smtpserverport' configuration variable. +--smtp-server-option=<option>:: + If set, specifies the outgoing SMTP server option to use. + Default value can be specified by the 'sendemail.smtpserveroption' + configuration option. ++ +The --smtp-server-option option must be repeated for each option you want +to pass to the server. Likewise, different lines in the configuration files +must be used for each option. + --smtp-ssl:: Legacy alias for '--smtp-encryption ssl'. @@ -177,6 +201,12 @@ user is prompted for a password while the input is masked for privacy. Automating ~~~~~~~~~~ +--to-cmd=<command>:: + Specify a command to execute once per patch file which + should generate patch file specific "To:" entries. + Output of this command must be single email address per line. + Default is the value of 'sendemail.tocmd' configuration value. + --cc-cmd=<command>:: Specify a command to execute once per patch file which should generate patch file specific "Cc:" entries. @@ -292,6 +322,9 @@ have been specified, in which case default to 'compose'. Default is the value of 'sendemail.validate'; if this is not set, default to '--validate'. +--force:: + Send emails even if safety checks would prevent it. + CONFIGURATION ------------- diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index 0f3ad81..6403126 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -3,24 +3,30 @@ git-shell(1) NAME ---- -git-shell - Restricted login shell for GIT-only SSH access +git-shell - Restricted login shell for Git-only SSH access SYNOPSIS -------- -'$(git --exec-path)/git-shell' -c <command> <argument> +'git shell' [-c <command> <argument>] DESCRIPTION ----------- -This is meant to be used as a login shell for SSH accounts you want -to restrict to GIT pull/push access only. It permits execution only -of server-side GIT commands implementing the pull/push functionality. -The commands can be executed only by the '-c' option; the shell is not -interactive. - -Currently, only four commands are permitted to be called, 'git-receive-pack' -'git-upload-pack' and 'git-upload-archive' with a single required argument, or -'cvs server' (to invoke 'git-cvsserver'). + +A login shell for SSH accounts to provide restricted Git access. When +'-c' is given, the program executes <command> non-interactively; +<command> can be one of 'git receive-pack', 'git upload-pack', 'git +upload-archive', 'cvs server', or a command in COMMAND_DIR. The shell +is started in interactive mode when no arguments are given; in this +case, COMMAND_DIR must exist, and any of the executables in it can be +invoked. + +'cvs server' is a special command which executes git-cvsserver. + +COMMAND_DIR is the path "$HOME/git-shell-commands". The user must have +read and execute permissions to the directory in order to execute the +programs in it. The programs are executed with a cwd of $HOME, and +<argument> is parsed as a command-line string. Author ------ diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index bc1ac77..5cc3baf 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -44,7 +44,7 @@ OPTIONS --email:: Show the email address of each author. ---format[='<format>']:: +--format[=<format>]:: Instead of the commit subject, use some other information to describe each commit. '<format>' can be any string accepted by the `--format` option of 'git log', such as '{asterisk} [%h] %s'. diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 6453263..3b0c882 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -12,7 +12,7 @@ SYNOPSIS [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] - [<rev> | <glob>]... + [(<rev> | <glob>)...] 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] @@ -32,7 +32,7 @@ no <rev> nor <glob> is given on the command line. OPTIONS ------- <rev>:: - Arbitrary extended SHA1 expression (see linkgit:gitrevisions[1]) + Arbitrary extended SHA1 expression (see linkgit:gitrevisions[7]) that typically names a branch head or a tag. <glob>:: diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index 4696af7..be0ec18 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -84,7 +84,11 @@ OPTIONS <pattern>...:: - Show references matching one or more patterns. + Show references matching one or more patterns. Patterns are matched from + the end of the full name, and only complete parts are matched, e.g. + 'master' matches 'refs/heads/master', 'refs/remotes/origin/master', + 'refs/tags/jedi/master' but not 'refs/heads/mymaster' nor + 'refs/remotes/master/jedi'. OUTPUT ------ diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index 0002bfb..f0a8a1a 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -36,7 +36,7 @@ OPTIONS <object>...:: The names of objects to show. For a more complete list of ways to spell object names, see - "SPECIFYING REVISIONS" section in linkgit:gitrevisions[1]. + "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. include::pretty-options.txt[] @@ -54,6 +54,10 @@ git show v1.0.0:: git show v1.0.0^\{tree\}:: Shows the tree pointed to by the tag `v1.0.0`. +git show -s --format=%s v1.0.0^\{commit\}:: + Shows the subject of the commit pointed to by the + tag `v1.0.0`. + git show next~10:Documentation/README:: Shows the contents of the file `Documentation/README` as they were current in the 10th last commit of the branch diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index be8a51f..139d314 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -438,7 +438,7 @@ git rebase --onto remotes/git-svn A^ master OPTIONS ------- ---shared[={false|true|umask|group|all|world|everybody}]:: +--shared[=(false|true|umask|group|all|world|everybody)]:: --template=<template_directory>:: Only used with the 'init' command. These are passed directly to 'git init'. diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 31c78a8..8b169e3 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -177,7 +177,7 @@ On Automatic following ~~~~~~~~~~~~~~~~~~~~~~ If you are following somebody else's tree, you are most likely -using tracking branches (`refs/heads/origin` in traditional +using remote-tracking branches (`refs/heads/origin` in traditional layout, or `refs/remotes/origin/master` in the separate-remote layout). You usually want the tags from the other end. @@ -232,7 +232,7 @@ this case. It may well be that among networking people, they may want to exchange the tags internal to their group, but in that workflow they are most likely tracking with each other's progress by -having tracking branches. Again, the heuristic to automatically +having remote-tracking branches. Again, the heuristic to automatically follow such tags is a good thing. diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 74d1d49..1ca56c8 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git update-index' [--add] [--remove | --force-remove] [--replace] [--refresh] [-q] [--unmerged] [--ignore-missing] - [--cacheinfo <mode> <object> <file>]* + [(--cacheinfo <mode> <object> <file>)...] [--chmod=(+|-)x] [--assume-unchanged | --no-assume-unchanged] [--skip-worktree | --no-skip-worktree] @@ -21,7 +21,7 @@ SYNOPSIS [--info-only] [--index-info] [-z] [--stdin] [--verbose] - [--] [<file>]* + [--] [<file>...] DESCRIPTION ----------- @@ -144,8 +144,8 @@ you will need to handle the situation manually. Report what is being added and removed from index. -z:: - Only meaningful with `--stdin`; paths are separated with - NUL character instead of LF. + Only meaningful with `--stdin` or `--index-info`; paths are + separated with NUL character instead of LF. \--:: Do not interpret any more arguments as options. diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index dada212..7112197 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -15,6 +15,10 @@ Validates the gpg signature created by 'git tag'. OPTIONS ------- +-v:: +--verbose:: + Print the contents of the tag object before validating it. + <tag>...:: SHA1 identifiers of git tag objects. diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index e1586c7..51e8e0a 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -32,19 +32,19 @@ Custom commands may also be specified. OPTIONS ------- --b BROWSER:: ---browser=BROWSER:: - Use the specified BROWSER. It must be in the list of supported +-b <browser>:: +--browser=<browser>:: + Use the specified browser. It must be in the list of supported browsers. --t BROWSER:: ---tool=BROWSER:: +-t <browser>:: +--tool=<browser>:: Same as above. --c CONF.VAR:: ---config=CONF.VAR:: +-c <conf.var>:: +--config=<conf.var>:: CONF.VAR is looked up in the git config files. If it's set, - then its value specify the browser that should be used. + then its value specifies the browser that should be used. CONFIGURATION VARIABLES ----------------------- diff --git a/Documentation/git.txt b/Documentation/git.txt index dd57bdc..8216083 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -9,11 +9,11 @@ git - the stupid content tracker SYNOPSIS -------- [verse] -'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path] +'git' [--version] [--exec-path[=<path>]] [--html-path] [-p|--paginate|--no-pager] [--no-replace-objects] - [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE] - [-c name=value] - [--help] COMMAND [ARGS] + [--bare] [--git-dir=<path>] [--work-tree=<path>] + [-c <name>=<value>] + [--help] <command> [<args>] DESCRIPTION ----------- @@ -28,7 +28,7 @@ also want to read linkgit:gitcvs-migration[7]. See the link:user-manual.html[Git User's Manual] for a more in-depth introduction. -The COMMAND is either a name of a Git command (see below) or an alias +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]). Formatted and hyperlinked version of the latest git @@ -44,30 +44,35 @@ 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.3.1/git.html[documentation for release 1.7.3.1] +* link:v1.7.3.3/git.html[documentation for release 1.7.3.3] * release notes for + link:RelNotes/1.7.3.3.txt[1.7.3.3], + link:RelNotes/1.7.3.2.txt[1.7.3.2], link:RelNotes/1.7.3.1.txt[1.7.3.1], link:RelNotes/1.7.3.txt[1.7.3]. -* link:v1.7.2.3/git.html[documentation for release 1.7.2.3] +* link:v1.7.2.4/git.html[documentation for release 1.7.2.4] * release notes for + link:RelNotes/1.7.2.4.txt[1.7.2.4], link:RelNotes/1.7.2.3.txt[1.7.2.3], link:RelNotes/1.7.2.2.txt[1.7.2.2], link:RelNotes/1.7.2.1.txt[1.7.2.1], link:RelNotes/1.7.2.txt[1.7.2]. -* link:v1.7.1.2/git.html[documentation for release 1.7.1.2] +* link:v1.7.1.3/git.html[documentation for release 1.7.1.3] * release notes for + link:RelNotes/1.7.1.3.txt[1.7.1.3], link:RelNotes/1.7.1.2.txt[1.7.1.2], link:RelNotes/1.7.1.1.txt[1.7.1.1], link:RelNotes/1.7.1.txt[1.7.1]. -* link:v1.7.0.7/git.html[documentation for release 1.7.0.7] +* link:v1.7.0.8/git.html[documentation for release 1.7.0.8] * release notes for + link:RelNotes/1.7.0.8.txt[1.7.0.8], link:RelNotes/1.7.0.7.txt[1.7.0.7], link:RelNotes/1.7.0.6.txt[1.7.0.6], link:RelNotes/1.7.0.5.txt[1.7.0.5], @@ -252,7 +257,7 @@ help ...`. The <name> is expected in the same format as listed by 'git config' (subkeys separated by dots). ---exec-path:: +--exec-path[=<path>]:: Path to wherever your core git programs are installed. This can also be controlled by setting the GIT_EXEC_PATH environment variable. If no path is given, 'git' will print @@ -495,7 +500,7 @@ HEAD:: (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). For a more complete list of ways to spell object names, see -"SPECIFYING REVISIONS" section in linkgit:gitrevisions[1]. +"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. File/Directory Structure diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index e5a27d8..c80ca5d 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -62,14 +62,21 @@ consults `$GIT_DIR/info/attributes` file (which has the highest precedence), `.gitattributes` file in the same directory as the path in question, and its parent directories up to the toplevel of the work tree (the further the directory that contains `.gitattributes` -is from the path in question, the lower its precedence). +is from the path in question, the lower its precedence). Finally +global and system-wide files are considered (they have the lowest +precedence). If you wish to affect only a single repository (i.e., to assign -attributes to files that are particular to one user's workflow), then +attributes to files that are particular to +one user's workflow for that repository), then attributes should be placed in the `$GIT_DIR/info/attributes` file. Attributes which should be version-controlled and distributed to other repositories (i.e., attributes of interest to all users) should go into -`.gitattributes` files. +`.gitattributes` files. Attributes that should affect all repositories +for a single user should be placed in a file specified by the +`core.attributesfile` configuration option (see linkgit:git-config[1]). +Attributes for all users on a system should be placed in the +`$(prefix)/etc/gitattributes` file. Sometimes you would need to override an setting of an attribute for a path to `unspecified` state. This can be done by listing @@ -477,6 +484,8 @@ patterns are available: - `csharp` suitable for source code in the C# language. +- `fortran` suitable for source code in the Fortran language. + - `html` suitable for HTML/XHTML documents. - `java` suitable for source code in the Java language. diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index 5e9c5eb..c27d086 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -971,7 +971,7 @@ commits from the master branch. The string inside brackets before the commit log message is a short name you can use to name the commit. In the above example, 'master' and 'mybranch' are branch heads. 'master^' is the first parent of 'master' -branch head. Please see linkgit:gitrevisions[1] if you want to +branch head. Please see linkgit:gitrevisions[7] if you want to see more complex cases. [NOTE] diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 5d91a7e..6af29a4 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -227,9 +227,9 @@ changes that touch a specified string, and is controlled by the commands. When diffcore-pickaxe is in use, it checks if there are -filepairs whose "result" side has the specified string and -whose "origin" side does not. Such a filepair represents "the -string appeared in this changeset". It also checks for the +filepairs whose "result" side and whose "origin" side have +different number of specified string. Such a filepair represents +"the string appeared in this changeset". It also checks for the opposite case that loses the specified string. When `\--pickaxe-all` is not in effect, diffcore-pickaxe leaves diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 7dc2e8b..8416f34 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -14,11 +14,8 @@ DESCRIPTION A `gitignore` file specifies intentionally untracked files that git should ignore. -Note that all the `gitignore` files really concern only files -that are not already tracked by git; -in order to ignore uncommitted changes in already tracked files, -please refer to the 'git update-index --assume-unchanged' -documentation. +Files already tracked by git are not affected; see the NOTES +below for details. Each line in a `gitignore` file specifies a pattern. When deciding whether to ignore a path, git normally checks @@ -62,7 +59,8 @@ files specified by command-line options. Higher-level git tools, such as 'git status' and 'git add', use patterns from the sources specified above. -Patterns have the following format: +PATTERN FORMAT +-------------- - A blank line matches no files, so it can serve as a separator for readability. @@ -98,7 +96,20 @@ Patterns have the following format: For example, "/{asterisk}.c" matches "cat-file.c" but not "mozilla-sha1/sha1.c". -An example: +NOTES +----- + +The purpose of gitignore files is to ensure that certain files +not tracked by git remain untracked. + +To ignore uncommitted changes in a file that is already tracked, +use 'git update-index {litdd}assume-unchanged'. + +To stop tracking a file that is currently tracked, use +'git rm --cached'. + +EXAMPLES +-------- -------------------------------------------------------------- $ git status @@ -140,6 +151,11 @@ Another example: The second .gitignore prevents git from ignoring `arch/foo/kernel/vmlinux.lds.S`. +SEE ALSO +-------- +linkgit:git-rm[1], linkgit:git-update-index[1], +linkgit:gitrepository-layout[5] + Documentation ------------- Documentation by David Greaves, Junio C Hamano, Josh Triplett, diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 05ac1c7..e21bac4 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -69,7 +69,7 @@ frequently used options. the form "'<from>'..'<to>'" to show all revisions between '<from>' and back to '<to>'. Note, more advanced revision selection can be applied. For a more complete list of ways to spell object names, see - linkgit:gitrevisions[1]. + linkgit:gitrevisions[7]. <path>...:: diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index ecab0c0..7fe5848 100644 --- a/Documentation/gittutorial-2.txt +++ b/Documentation/gittutorial-2.txt @@ -373,7 +373,7 @@ $ git status # # new file: closing.txt # -# Changed but not updated: +# Changes not staged for commit: # (use "git add <file>..." to update what will be committed) # # modified: file.txt diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt index 1c16066..0982f74 100644 --- a/Documentation/gittutorial.txt +++ b/Documentation/gittutorial.txt @@ -385,7 +385,7 @@ alice$ git fetch bob Unlike the longhand form, when Alice fetches from Bob using a remote repository shorthand set up with 'git remote', what was -fetched is stored in a remote tracking branch, in this case +fetched is stored in a remote-tracking branch, in this case `bob/master`. So after this: ------------------------------------- @@ -402,8 +402,8 @@ could merge the changes into her master branch: alice$ git merge bob/master ------------------------------------- -This `merge` can also be done by 'pulling from her own remote -tracking branch', like this: +This `merge` can also be done by 'pulling from her own remote-tracking +branch', like this: ------------------------------------- alice$ git pull . remotes/bob/master diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 1f029f8..f04b48e 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -131,7 +131,7 @@ to point at the new commit. you have. In such these cases, you do not make a new <<def_merge,merge>> <<def_commit,commit>> but instead just update to his revision. This will happen frequently on a - <<def_tracking_branch,tracking branch>> of a remote + <<def_remote_tracking_branch,remote-tracking branch>> of a remote <<def_repository,repository>>. [[def_fetch]]fetch:: @@ -260,7 +260,7 @@ This commit is referred to as a "merge commit", or sometimes just a The default upstream <<def_repository,repository>>. Most projects have at least one upstream project which they track. By default 'origin' is used for that purpose. New upstream updates - will be fetched into remote <<def_tracking_branch,tracking branches>> named + will be fetched into remote <<def_remote_tracking_branch,remote-tracking branches>> named origin/name-of-upstream-branch, which you can see using `git branch -r`. @@ -349,6 +349,14 @@ This commit is referred to as a "merge commit", or sometimes just a master branch head as to-upstream branch at $URL". See also linkgit:git-push[1]. +[[def_remote_tracking_branch]]remote-tracking branch:: + A regular git <<def_branch,branch>> that is used to follow changes from + another <<def_repository,repository>>. A remote-tracking + branch should not contain direct modifications or have local commits + made to it. A remote-tracking branch can usually be + identified as the right-hand-side <<def_ref,ref>> in a Pull: + <<def_refspec,refspec>>. + [[def_repository]]repository:: A collection of <<def_ref,refs>> together with an <<def_object_database,object database>> containing all objects @@ -418,14 +426,6 @@ This commit is referred to as a "merge commit", or sometimes just a that each contain very well defined concepts or small incremental yet related changes. -[[def_tracking_branch]]tracking branch:: - A regular git <<def_branch,branch>> that is used to follow changes from - another <<def_repository,repository>>. A tracking - branch should not contain direct modifications or have local commits - made to it. A tracking branch can usually be - identified as the right-hand-side <<def_ref,ref>> in a Pull: - <<def_refspec,refspec>>. - [[def_tree]]tree:: Either a <<def_working_tree,working tree>>, or a <<def_tree_object,tree object>> together with the dependent <<def_blob_object,blob>> and tree objects diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index b72f533..92772e7 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -7,8 +7,10 @@ merge.conflictstyle:: marker and the original text before the `=======` marker. merge.log:: - Whether to include summaries of merged commits in newly created - merge commit messages. False by default. + In addition to branch names, populate the log message with at + most the specified number of one-line descriptions from the + actual commits that are being merged. Defaults to false, and + true is a synoym for 20. merge.renameLimit:: The number of files to consider when performing rename detection diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 722d704..e33e0f8 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -16,11 +16,11 @@ inspect and further tweak the merge result before committing. With --no-ff Generate a merge commit even if the merge resolved as a fast-forward. ---log:: +--log[=<n>]:: --no-log:: In addition to branch names, populate the log message with - one-line descriptions from the actual commits that are being - merged. + one-line descriptions from at most <n> actual commits that are being + merged. See also linkgit:git-fmt-merge-msg[1]. + With --no-log do not list one-line descriptions from the actual commits being merged. diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 049313d..595a3cf 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -40,6 +40,28 @@ the other tree did, declaring 'our' history contains all that happened in it. theirs;; This is opposite of 'ours'. +patience;; + With this option, 'merge-recursive' spends a little extra time + to avoid mismerges that sometimes occur due to unimportant + matching lines (e.g., braces from distinct functions). Use + this when the branches to be merged have diverged wildly. + See also linkgit:git-diff[1] `--patience`. + +ignore-space-change;; +ignore-all-space;; +ignore-space-at-eol;; + Treats lines with the indicated type of whitespace change as + unchanged for the sake of a three-way merge. Whitespace + changes mixed with other changes to a line are not ignored. + See also linkgit:git-diff[1] `-b`, `-w`, and + `--ignore-space-at-eol`. ++ +* If 'their' version only introduces whitespace changes to a line, + 'our' version is used; +* If 'our' version introduces whitespace changes but 'their' + version includes a substantial change, 'their' version is used; +* Otherwise, the merge proceeds in the usual way. + renormalize;; This runs a virtual check-out and check-in of all three stages of a file when resolving a three-way merge. This option is @@ -52,7 +74,11 @@ no-renormalize;; Disables the `renormalize` option. This overrides the `merge.renormalize` configuration variable. -subtree[=path];; +rename-threshold=<n>;; + Controls the similarity threshold used for rename detection. + See also linkgit:git-diff[1] `-M`. + +subtree[=<path>];; This option is a more advanced form of 'subtree' strategy, where the strategy makes a guess on how two trees must be shifted to match with each other when merging. Instead, the specified path diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 9b6f389..50923e2 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -1,5 +1,5 @@ ---pretty[='<format>']:: ---format='<format>':: +--pretty[=<format>]:: +--format=<format>:: Pretty-print the contents of the commit logs in a given format, where '<format>' can be one of 'oneline', 'short', 'medium', diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index ebc0108..44a2ef1 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -13,7 +13,7 @@ include::pretty-options.txt[] Synonym for `--date=relative`. ---date={relative,local,default,iso,rfc,short,raw}:: +--date=(relative|local|default|iso|rfc|short|raw):: Only takes effect for dates shown in human-readable format, such as when using "--pretty". `log.date` config variable sets a default @@ -95,6 +95,8 @@ you would get an output like this: to be printed in between commits, in order for the graph history to be drawn properly. + +This enables parent rewriting, see 'History Simplification' below. ++ This implies the '--topo-order' option by default, but the '--date-order' option may also be specified. @@ -146,6 +148,9 @@ options may be given. See linkgit:git-diff-files[1] for more options. -t:: Show the tree objects in the diff output. This implies '-r'. + +-s:: + Suppress diff output. endif::git-rev-list[] Commit Limiting @@ -246,29 +251,29 @@ endif::git-rev-list[] Pretend as if all the refs in `refs/` are listed on the command line as '<commit>'. ---branches[=pattern]:: +--branches[=<pattern>]:: Pretend as if all the refs in `refs/heads` are listed - on the command line as '<commit>'. If `pattern` is given, limit + on the command line as '<commit>'. If '<pattern>' is given, limit branches to ones matching given shell glob. If pattern lacks '?', '*', or '[', '/*' at the end is implied. ---tags[=pattern]:: +--tags[=<pattern>]:: Pretend as if all the refs in `refs/tags` are listed - on the command line as '<commit>'. If `pattern` is given, limit + on the command line as '<commit>'. If '<pattern>' is given, limit tags to ones matching given shell glob. If pattern lacks '?', '*', or '[', '/*' at the end is implied. ---remotes[=pattern]:: +--remotes[=<pattern>]:: Pretend as if all the refs in `refs/remotes` are listed - on the command line as '<commit>'. If `pattern`is given, limit - remote tracking branches to ones matching given shell glob. + on the command line as '<commit>'. If '<pattern>' is given, limit + remote-tracking branches to ones matching given shell glob. If pattern lacks '?', '*', or '[', '/*' at the end is implied. ---glob=glob-pattern:: - Pretend as if all the refs matching shell glob `glob-pattern` +--glob=<glob-pattern>:: + Pretend as if all the refs matching shell glob '<glob-pattern>' are listed on the command line as '<commit>'. Leading 'refs/', is automatically prepended if missing. If pattern lacks '?', '*', or '[', '/*' at the end is implied. diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt index a7e050b..9dc1bed 100644 --- a/Documentation/technical/api-merge.txt +++ b/Documentation/technical/api-merge.txt @@ -17,6 +17,40 @@ responsible for a few things. path-specific merge drivers (specified in `.gitattributes`) into account. +Data structures +--------------- + +* `mmbuffer_t`, `mmfile_t` + +These store data usable for use by the xdiff backend, for writing and +for reading, respectively. See `xdiff/xdiff.h` for the definitions +and `diff.c` for examples. + +* `struct ll_merge_options` + +This describes the set of options the calling program wants to affect +the operation of a low-level (single file) merge. Some options: + +`virtual_ancestor`:: + Behave as though this were part of a merge between common + ancestors in a recursive merge. + If a helper program is specified by the + `[merge "<driver>"] recursive` configuration, it will + be used (see linkgit:gitattributes[5]). + +`variant`:: + Resolve local conflicts automatically in favor + of one side or the other (as in 'git merge-file' + `--ours`/`--theirs`/`--union`). Can be `0`, + `XDL_MERGE_FAVOR_OURS`, `XDL_MERGE_FAVOR_THEIRS`, or + `XDL_MERGE_FAVOR_UNION`. + +`renormalize`:: + Resmudge and clean the "base", "theirs" and "ours" files + before merging. Use this when the merge is likely to have + overlapped with a change in smudge/clean or end-of-line + normalization rules. + Low-level (single file) merge ----------------------------- @@ -28,15 +62,24 @@ Low-level (single file) merge `.git/info/attributes` into account. Returns 0 for a clean merge. -The caller: +Calling sequence: -1. allocates an mmbuffer_t variable for the result; -2. allocates and fills variables with the file's original content - and two modified versions (using `read_mmfile`, for example); -3. calls ll_merge(); -4. reads the output from result_buf.ptr and result_buf.size; -5. releases buffers when finished (free(ancestor.ptr); free(ours.ptr); - free(theirs.ptr); free(result_buf.ptr);). +* Prepare a `struct ll_merge_options` to record options. + If you have no special requests, skip this and pass `NULL` + as the `opts` parameter to use the default options. + +* Allocate an mmbuffer_t variable for the result. + +* Allocate and fill variables with the file's original content + and two modified versions (using `read_mmfile`, for example). + +* Call `ll_merge()`. + +* Read the merged content from `result_buf.ptr` and `result_buf.size`. + +* Release buffers when finished. A simple + `free(ancestor.ptr); free(ours.ptr); free(theirs.ptr); + free(result_buf.ptr);` will do. If the modifications do not merge cleanly, `ll_merge` will return a nonzero value and `result_buf` will generally include a description of @@ -47,18 +90,6 @@ The `ancestor_label`, `our_label`, and `their_label` parameters are used to label the different sides of a conflict if the merge driver supports this. -The `flag` parameter is a bitfield: - - - The `LL_OPT_VIRTUAL_ANCESTOR` bit indicates whether this is an - internal merge to consolidate ancestors for a recursive merge. - - - The `LL_OPT_FAVOR_MASK` bits allow local conflicts to be automatically - resolved in favor of one side or the other (as in 'git merge-file' - `--ours`/`--theirs`/`--union`). - They can be populated by `create_ll_flag`, whose argument can be - `XDL_MERGE_FAVOR_OURS`, `XDL_MERGE_FAVOR_THEIRS`, or - `XDL_MERGE_FAVOR_UNION`. - Everything else --------------- diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index c5d141c..f6a4a36 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -118,13 +118,16 @@ There are some macros to easily define options: `OPT__COLOR(&int_var, description)`:: Add `\--color[=<when>]` and `--no-color`. -`OPT__DRY_RUN(&int_var)`:: +`OPT__DRY_RUN(&int_var, description)`:: Add `-n, \--dry-run`. -`OPT__QUIET(&int_var)`:: +`OPT__FORCE(&int_var, description)`:: + Add `-f, \--force`. + +`OPT__QUIET(&int_var, description)`:: Add `-q, \--quiet`. -`OPT__VERBOSE(&int_var)`:: +`OPT__VERBOSE(&int_var, description)`:: Add `-v, \--verbose`. `OPT_GROUP(description)`:: diff --git a/Documentation/technical/api-sigchain.txt b/Documentation/technical/api-sigchain.txt new file mode 100644 index 0000000..535cdff --- /dev/null +++ b/Documentation/technical/api-sigchain.txt @@ -0,0 +1,41 @@ +sigchain API +============ + +Code often wants to set a signal handler to clean up temporary files or +other work-in-progress when we die unexpectedly. For multiple pieces of +code to do this without conflicting, each piece of code must remember +the old value of the handler and restore it either when: + + 1. The work-in-progress is finished, and the handler is no longer + necessary. The handler should revert to the original behavior + (either another handler, SIG_DFL, or SIG_IGN). + + 2. The signal is received. We should then do our cleanup, then chain + to the next handler (or die if it is SIG_DFL). + +Sigchain is a tiny library for keeping a stack of handlers. Your handler +and installation code should look something like: + +------------------------------------------ + void clean_foo_on_signal(int sig) + { + clean_foo(); + sigchain_pop(sig); + raise(sig); + } + + void other_func() + { + sigchain_push_common(clean_foo_on_signal); + mess_up_foo(); + clean_foo(); + } +------------------------------------------ + +Handlers are given the typdef of sigchain_fun. This is the same type +that is given to signal() or sigaction(). It is perfectly reasonable to +push SIG_DFL or SIG_IGN onto the stack. + +You can sigchain_push and sigchain_pop individual signals. For +convenience, sigchain_push_common will push the handler onto the stack +for many common signals. diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index ce45bfc..f13a846 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -344,7 +344,8 @@ Examining branches from a remote repository The "master" branch that was created at the time you cloned is a copy of the HEAD in the repository that you cloned from. That repository may also have had other branches, though, and your local repository -keeps branches which track each of those remote branches, which you +keeps branches which track each of those remote branches, called +remote-tracking branches, which you can view using the "-r" option to linkgit:git-branch[1]: ------------------------------------------------ @@ -359,13 +360,23 @@ $ git branch -r origin/todo ------------------------------------------------ -You cannot check out these remote-tracking branches, but you can -examine them on a branch of your own, just as you would a tag: +In this example, "origin" is called a remote repository, or "remote" +for short. The branches of this repository are called "remote +branches" from our point of view. The remote-tracking branches listed +above were created based on the remote branches at clone time and will +be updated by "git fetch" (hence "git pull") and "git push". See +<<Updating-a-repository-With-git-fetch>> for details. + +You might want to build on one of these remote-tracking branches +on a branch of your own, just as you would for a tag: ------------------------------------------------ $ git checkout -b my-todo-copy origin/todo ------------------------------------------------ +You can also check out "origin/todo" directly to examine it or +write a one-off patch. See <<detached-head,detached head>>. + Note that the name "origin" is just the name that git uses by default to refer to the repository that you cloned from. @@ -397,7 +408,7 @@ is usually a shortcut for the HEAD branch in the repository "origin". For the complete list of paths which git checks for references, and the order it uses to decide which to choose when there are multiple references with the same shorthand name, see the "SPECIFYING -REVISIONS" section of linkgit:gitrevisions[1]. +REVISIONS" section of linkgit:gitrevisions[7]. [[Updating-a-repository-With-git-fetch]] Updating a repository with git fetch @@ -435,7 +446,7 @@ linux-nfs/master origin/master ------------------------------------------------- -If you run "git fetch <remote>" later, the tracking branches for the +If you run "git fetch <remote>" later, the remote-tracking branches for the named <remote> will be updated. If you examine the file .git/config, you will see that git has added @@ -568,7 +579,7 @@ We have seen several ways of naming commits already: - HEAD: refers to the head of the current branch There are many more; see the "SPECIFYING REVISIONS" section of the -linkgit:gitrevisions[1] man page for the complete list of ways to +linkgit:gitrevisions[7] man page for the complete list of ways to name revisions. Some examples: ------------------------------------------------- @@ -909,7 +920,7 @@ commits reachable from some head but not from any tag in the repository: $ gitk $( git show-ref --heads ) --not $( git show-ref --tags ) ------------------------------------------------- -(See linkgit:gitrevisions[1] for explanations of commit-selecting +(See linkgit:gitrevisions[7] for explanations of commit-selecting syntax such as `--not`.) [[making-a-release]] @@ -1635,7 +1646,7 @@ you've checked out. The reflogs are kept by default for 30 days, after which they may be pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn how to control this pruning, and see the "SPECIFYING REVISIONS" -section of linkgit:gitrevisions[1] for details. +section of linkgit:gitrevisions[7] for details. Note that the reflog history is very different from normal git history. While normal history is shared by every repository that works on the @@ -1700,7 +1711,7 @@ may wish to check the original repository for updates and merge them into your own work. We have already seen <<Updating-a-repository-With-git-fetch,how to -keep remote tracking branches up to date>> with linkgit:git-fetch[1], +keep remote-tracking branches up to date>> with linkgit:git-fetch[1], and how to merge two branches. So you can merge in changes from the original repository's master branch with: @@ -1716,15 +1727,21 @@ one step: $ git pull origin master ------------------------------------------------- -In fact, if you have "master" checked out, then by default "git pull" -merges from the HEAD branch of the origin repository. So often you can +In fact, if you have "master" checked out, then this branch has been +configured by "git clone" to get changes from the HEAD branch of the +origin repository. So often you can accomplish the above with just a simple ------------------------------------------------- $ git pull ------------------------------------------------- -More generally, a branch that is created from a remote branch will pull +This command will fetch changes from the remote branches to your +remote-tracking branches `origin/*`, and merge the default branch into +the current branch. + +More generally, a branch that is created from a remote-tracking branch +will pull by default from that branch. See the descriptions of the branch.<name>.remote and branch.<name>.merge options in linkgit:git-config[1], and the discussion of the `--track` option in @@ -2106,7 +2123,7 @@ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git $ cd work ------------------------------------------------- -Linus's tree will be stored in the remote branch named origin/master, +Linus's tree will be stored in the remote-tracking branch named origin/master, and can be updated using linkgit:git-fetch[1]; you can track other public trees using linkgit:git-remote[1] to set up a "remote" and linkgit:git-fetch[1] to keep them up-to-date; see @@ -2171,11 +2188,14 @@ $ git push mytree release Now to apply some patches from the community. Think of a short snappy name for a branch to hold this patch (or related group of -patches), and create a new branch from the current tip of Linus's -branch: +patches), and create a new branch from a recent stable tag of +Linus's branch. Picking a stable base for your branch will: +1) help you: by avoiding inclusion of unrelated and perhaps lightly +tested changes +2) help future bug hunters that use "git bisect" to find problems ------------------------------------------------- -$ git checkout -b speed-up-spinlocks origin +$ git checkout -b speed-up-spinlocks v2.6.35 ------------------------------------------------- Now you apply the patch(es), run some tests, and commit the change(s). If @@ -2797,8 +2817,8 @@ Be aware that commits that the old version of example/master pointed at may be lost, as we saw in the previous section. [[remote-branch-configuration]] -Configuring remote branches ---------------------------- +Configuring remote-tracking branches +------------------------------------ We saw above that "origin" is just a shortcut to refer to the repository that you originally cloned from. This information is @@ -3850,7 +3870,7 @@ You create a commit object by giving it the tree that describes the state at the time of the commit, and a list of parents: ------------------------------------------------- -$ git commit-tree <tree> -p <parent> [-p <parent2> ..] +$ git commit-tree <tree> -p <parent> [(-p <parent2>)...] ------------------------------------------------- and then giving the reason for the commit on stdin (either through |