diff options
Diffstat (limited to 'Documentation')
174 files changed, 2514 insertions, 1776 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 46f8a3fab1..fe1c1e5bc2 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -143,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 spelled in lowercase and enclosed in angle brackets: + <file> + --sort=<key> + --abbrev[=<n>] + + Possibility of multiple occurrences 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/Makefile b/Documentation/Makefile index e117bc4315..36989b7f65 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -63,35 +63,28 @@ endif # # For asciidoc ... -# -7.1.2, no extra settings are needed. -# 8.0-, set ASCIIDOC8. +# -7.1.2, set ASCIIDOC7 +# 8.0-, no extra settings are needed # # # For docbook-xsl ... -# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) -# 1.69.0, no extra settings are needed? +# -1.68.1, no extra settings are needed? +# 1.69.0, set ASCIIDOC_ROFF? # 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? -# 1.71.1, no extra settings are needed? +# 1.71.1, set ASCIIDOC_ROFF? # 1.72.0, set DOCBOOK_XSL_172. -# 1.73.0-, set ASCIIDOC_NO_ROFF +# 1.73.0-, no extra settings are needed # -# -# If you had been using DOCBOOK_XSL_172 in an attempt to get rid -# of 'the ".ft C" problem' in your generated manpages, and you -# instead ended up with weird characters around callouts, try -# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8). -# - -ifdef ASCIIDOC8 +ifndef ASCIIDOC7 ASCIIDOC_EXTRA += -a asciidoc7compatible -a no-inline-literal endif ifdef DOCBOOK_XSL_172 ASCIIDOC_EXTRA += -a git-asciidoc-no-roff MANPAGE_XSL = manpage-1.72.xsl else - ifdef ASCIIDOC_NO_ROFF + ifndef ASCIIDOC_ROFF # docbook-xsl after 1.72 needs the regular XSL, but will not # pass-thru raw roff codes from asciidoc.conf, so turn them off. ASCIIDOC_EXTRA += -a git-asciidoc-no-roff diff --git a/Documentation/RelNotes/1.7.4.1.txt b/Documentation/RelNotes/1.7.4.1.txt new file mode 100644 index 0000000000..79923a6d2f --- /dev/null +++ b/Documentation/RelNotes/1.7.4.1.txt @@ -0,0 +1,27 @@ +Git v1.7.4.1 Release Notes +========================== + +Fixes since v1.7.4 +------------------ + + * On Windows platform, the codepath to spawn a new child process forgot + to first flush the output buffer. + + * "git bundle" did not use OFS_DELTA encoding, making its output a few + per-cent larger than necessarily. + + * The option to tell "git clone" to recurse into the submodules was + misspelled with an underscore "--recurse_submodules". + + * "git diff --cached HEAD" before the first commit does what an end user + would expect (namely, show what would be committed without further "git + add"). + + * "git fast-import" didn't accept the command to ask for "notes" feature + to be present in its input stream, even though it was capable of the + feature. + + * "git fsck" gave up scanning loose object files in directories with + garbage files. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.4.2.txt b/Documentation/RelNotes/1.7.4.2.txt new file mode 100644 index 0000000000..ef4ce1fcd3 --- /dev/null +++ b/Documentation/RelNotes/1.7.4.2.txt @@ -0,0 +1,58 @@ +Git v1.7.4.2 Release Notes +========================== + +Fixes since v1.7.4.1 +-------------------- + + * Many documentation updates to match "git cmd -h" output and the + git-cmd manual page. + + * We used to keep one file descriptor open for each and every packfile + that we have a mmap window on it (read: "in use"), even when for very + tiny packfiles. We now close the file descriptor early when the entire + packfile fits inside one mmap window. + + * "git bisect visualize" tried to run "gitk" in windowing + environments even when "gitk" is not installed, resulting in a + strange error message. + + * "git clone /no/such/path" did not fail correctly. + + * "git commit" did not correctly error out when the user asked to use a + non existent file as the commit message template. + + * "git diff --stat -B" ran on binary files counted the changes in lines, + which was nonsensical. + + * "git diff -M" opportunistically detected copies, which was not + necessarily a good thing, especially when it is internally run by + recursive merge. + + * "git difftool" didn't tell (g)vimdiff that the files it is reading are + to be opened read-only. + + * "git merge" didn't pay attention to prepare-commit-msg hook, even + though if a merge is conflicted and manually resolved, the subsequent + "git commit" would have triggered the hook, which was inconsistent. + + * "git patch-id" (and commands like "format-patch --ignore-in-upstream" + that use it as their internal logic) handled changes to files that end + with incomplete lines incorrectly. + + * The official value to tell "git push" to push the current branch back + to update the upstream branch it forked from is now called "upstream". + The old name "tracking" is and will be supported. + + * "git submodule update" used to honor the --merge/--rebase option (or + corresponding configuration variables) even for a newly cloned + subproject, which made no sense (so/submodule-no-update-first-time). + + * gitweb's "highlight" interface mishandled tabs. + + * gitweb didn't understand timezones with GMT offset that is not + multiple of a whole hour. + + * gitweb had a few forward-incompatible syntactic constructs and + also used incorrect variable when showing the file mode in a diff. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.4.3.txt b/Documentation/RelNotes/1.7.4.3.txt new file mode 100644 index 0000000000..02a3d5bdf6 --- /dev/null +++ b/Documentation/RelNotes/1.7.4.3.txt @@ -0,0 +1,32 @@ +Git v1.7.4.3 Release Notes +========================== + +Fixes since v1.7.4.2 +-------------------- + + * "git apply" used to confuse lines updated by previous hunks as lines + that existed before when applying a hunk, contributing misapplication + of patches with offsets. + + * "git branch --track" (and "git checkout --track --branch") used to + allow setting up a random non-branch that does not make sense to follow + as the "upstream". The command correctly diagnoses it as an error. + + * "git checkout $other_branch" silently removed untracked symbolic links + in the working tree that are in the way in order to check out paths + under it from the named branch. + + * "git cvsimport" did not bail out immediately when the cvs server cannot + be reached, spewing unnecessary error messages that complain about the + server response that it never got. + + * "git diff --quiet" did not work very well with the "--diff-filter" + option. + + * "git grep -n" lacked a long-hand synonym --line-number. + + * "git stash apply" reported the result of its operation by running + "git status" from the top-level of the working tree; it should (and + now does) run it from the user's working directory. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.4.4.txt b/Documentation/RelNotes/1.7.4.4.txt new file mode 100644 index 0000000000..ff06e04a58 --- /dev/null +++ b/Documentation/RelNotes/1.7.4.4.txt @@ -0,0 +1,35 @@ +Git v1.7.4.4 Release Notes +========================== + +Fixes since v1.7.4.3 +-------------------- + + * Compilation of sha1_file.c on BSD platforms were broken due to our + recent use of getrlimit() without including <sys/resource.h>. + + * "git config" did not diagnose incorrect configuration variable names. + + * "git format-patch" did not wrap a long subject line that resulted from + rfc2047 encoding. + + * "git instaweb" should work better again with plackup. + + * "git log --max-count=4 -Sfoobar" now shows 4 commits that changes the + number of occurrences of string "foobar"; it used to scan only for 4 + commits and then emitted only matching ones. + + * "git log --first-parent --boundary $c^..$c" segfaulted on a merge. + + * "git pull" into an empty branch should have behaved as if + fast-forwarding from emptiness to the version being pulled, with + the usual protection against overwriting untracked files. + + * "git submodule" that is run while a merge in the superproject is in + conflicted state tried to process each conflicted submodule up to + three times. + + * "git status" spent all the effort to notice racily-clean index entries + but didn't update the index file to help later operations go faster in + some cases. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.4.5.txt b/Documentation/RelNotes/1.7.4.5.txt new file mode 100644 index 0000000000..b7a0eeb22f --- /dev/null +++ b/Documentation/RelNotes/1.7.4.5.txt @@ -0,0 +1,4 @@ +Git v1.7.4.5 Release Notes +========================== + +This contains only minor documentation fixes accumulated since 1.7.4.4. diff --git a/Documentation/RelNotes/1.7.4.txt b/Documentation/RelNotes/1.7.4.txt new file mode 100644 index 0000000000..d5bca731b5 --- /dev/null +++ b/Documentation/RelNotes/1.7.4.txt @@ -0,0 +1,156 @@ +Git v1.7.4 Release Notes +======================== + +Updates since v1.7.3 +-------------------- + + * The documentation Makefile now assumes by default asciidoc 8 and + docbook-xsl >= 1.73. If you have older versions, you can set + ASCIIDOC7 and ASCIIDOC_ROFF, respectively. + + * The option parsers of various commands that create new branches (or + rename existing ones to a new name) were too loose and users were + allowed to give a branch a name that begins with a dash by creative + abuse of their command line options, which only led to burning + themselves. The name of a branch cannot begin with a dash now. + + * System-wide fallback default attributes can be stored in + /etc/gitattributes; the 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. + + * The Bash completion script in contrib/ has been adjusted to be usable with + Bash 4 (options with '=value' didn't complete). It has been also made + usable with zsh. + + * Different pagers can be chosen depending on which subcommand is + being run under the pager, using the "pager.<subcommand>" variable. + + * The hardcoded tab-width of 8 that is used in whitespace breakage checks is now + configurable via the attributes mechanism. + + * Support of case insensitive filesystems (i.e. "core.ignorecase") has + been improved. For example, the gitignore mechanism didn't pay attention + to case insensitivity. + + * The <tree>:<path> syntax for naming a blob in a tree, and the :<path> + syntax for naming a blob in the index (e.g. "master:Makefile", + ":hello.c") have been extended. You can start <path> with "./" to + implicitly have the (sub)directory you are in prefixed to the + lookup. Similarly, ":../Makefile" from a subdirectory would mean + "the Makefile of the parent directory in the index". + + * "git blame" learned the --show-email option to display the e-mail + addresses instead of the names of authors. + + * "git commit" learned the --fixup and --squash options to help later invocation + of interactive rebase. + + * Command line options to "git cvsimport" whose names are in capital + letters (-A, -M, -R and -S) can now be specified as the default in + the .git/config file by their longer names (cvsimport.authorsFile, + cvsimport.mergeRegex, cvsimport.trackRevisions, cvsimport.ignorePaths). + + * "git daemon" can be built in the MinGW environment. + + * "git daemon" can take more than one --listen option to listen to + multiple addresses. + + * "git describe --exact-match" was optimized not to read commit + objects unnecessarily. + + * "git diff" and "git grep" learned what functions and subroutines + in Fortran, Pascal and Perl look like. + + * "git fetch" learned the "--recurse-submodules" option. + + * "git mergetool" tells vim/gvim to show a three-way diff by default + (use vimdiff2/gvimdiff2 as the tool name for old behavior). + + * "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 + e.g. after you changed the core.compression variable setting). + + * "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 merge" learned the "--abort" option, synonymous to + "git reset --merge" when a merge is in progress. + + * "git notes" learned the "merge" subcommand to merge notes refs. + In addition to the default manual conflict resolution, there are + also several notes merge strategies for automatically resolving + notes merge conflicts. + + * "git rebase --autosquash" can use SHA-1 object names to name the + commit which is to be fixed up (e.g. "fixup! e83c5163"). + + * The default "recursive" merge strategy learned the --rename-threshold + option to influence the rename detection, similar to the -M option + of "git diff". From the "git merge" frontend, the "-X<strategy option>" + interface, e.g. "git merge -Xrename-threshold=50% ...", can be used + to trigger 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 + the 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 a custom set of + commands. + + * The current branch name in "git status" output can be colored differently + from the generic header color by setting the "color.status.branch" variable. + + * "git submodule sync" updates metainformation for all submodules, + not just the ones that have been checked out. + + * gitweb can use a custom 'highlight' command with its configuration file. + + * other gitweb updates. + + +Also contains various documentation updates. + + +Fixes since v1.7.3 +------------------ + +All of the fixes in the v1.7.3.X maintenance series are included in this +release, unless otherwise noted. + + * "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 push --progress" shows progress indicators now. + + * "git rebase -i" showed a confusing error message when given a + branch name that does not exist. + + * "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. diff --git a/Documentation/RelNotes/1.7.5.1.txt b/Documentation/RelNotes/1.7.5.1.txt new file mode 100644 index 0000000000..c6ebd76d19 --- /dev/null +++ b/Documentation/RelNotes/1.7.5.1.txt @@ -0,0 +1,47 @@ +Git v1.7.5.1 Release Notes +========================== + +Fixes since v1.7.5 +------------------ + + * When an object "$tree:$path" does not exist, if $path does exist in the + subtree of $tree that corresponds to the subdirectory the user is in, + git now suggests using "$tree:./$path" in addition to the advice to use + the full path from the root of the working tree. + + * The "--date=relative" output format used to say "X years, 12 months" + when it should have said "X+1 years". + + * The smart-HTTP transfer was broken in 1.7.5 when the client needs + to issue a small POST (which uses content-length) and then a large + POST (which uses chunked) back to back. + + * "git clean" used to fail on an empty directory that is not readable, + even though rmdir(2) could remove such a directory. Now we attempt it + as the last resort. + + * The "--dirstat" option of "diff" family of commands used to totally + ignore a change that only rearranged lines within a file. Such a + change now counts as at least a minimum but non zero change. + + * The "--dirstat" option of "diff" family of commands used to use the + pathname in the original, instead of the pathname in the result, + when renames are involved. + + * "git pack-object" did not take core.bigfilethreashold into account + (unlike fast-import); now it does. + + * "git reflog" ignored options like "--format=.." on the command line. + + * "git stash apply" used to refuse to work if there was any change in + the working tree, even when the change did not overlap with the change + the stash recorded. + + * "git stash apply @{99999}" was not diagnosed as an error, even when you + did not have that many stash entries. + + * An error message from "git send-email" to diagnose a broken SMTP + connection configuration lacked a space between "hello=<smtp-domain>" + and "port=<smtp-server-port>". + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.5.txt b/Documentation/RelNotes/1.7.5.txt new file mode 100644 index 0000000000..987919c321 --- /dev/null +++ b/Documentation/RelNotes/1.7.5.txt @@ -0,0 +1,132 @@ +Git v1.7.5 Release Notes +======================== + +Updates since v1.7.4 +-------------------- + + * Various MinGW portability fixes. + + * Various git-p4 enhancements (in contrib). + + * Various vcs-svn, git-svn and gitk enhancements and fixes. + + * Various git-gui updates (0.14.0). + + * Update to more modern HP-UX port. + + * The codebase is getting prepared for i18n/l10n; no translated + strings nor translation mechanism in the code yet, but the strings + are being marked for l10n. + + * The bash completion script can now complete symmetric difference + for "git diff" command, e.g. "git diff ...bra<TAB>". + + * The default minimum length of abbreviated and unique object names + can now be configured by setting the core.abbrev configuration + variable. + + * "git apply -v" reports offset lines when the patch does not apply at + the exact location recorded in the diff output. + + * "git config" used to be also known as "git repo-config", but the old + name is now officially deprecated. + + * "git checkout --detach <commit>" is a more user friendly synonym for + "git checkout <commit>^0". + + * "git checkout" performed on detached HEAD gives a warning and + advice when the commit being left behind will become unreachable from + any branch or tag. + + * "git cherry-pick" and "git revert" can be told to use a custom merge + strategy, similar to "git rebase". + + * "git cherry-pick" remembers which commit failed to apply when it is + stopped by conflicts, making it unnecessary to use "commit -c $commit" + to conclude it. + + * "git cvsimport" bails out immediately when the cvs server cannot be + reached, without spewing unnecessary error messages that complain about + the server response it never got. + + * "git fetch" vs "git upload-pack" transfer learned 'no-done' + protocol extension to save one round-trip after the content + negotiation is done. This saves one HTTP RPC, reducing the overall + latency for a trivial fetch. + + * "git fetch" can be told to recursively fetch submodules on-demand. + + * "git grep -f <filename>" learned to treat "-" as "read from the + standard input stream". + + * "git grep --no-index" did not honor pathspecs correctly, returning + paths outside the specified area. + + * "git init" learned the --separate-git-dir option to allow the git + directory for a new repository created elsewhere and linked via the + gitdir mechanism. This is primarily to help submodule support later + to switch between a branch of superproject that has the submodule + and another that does not. + + * "git log" type commands now understand globbing pathspecs. You + can say "git log -- '*.txt'" for example. + + * "git log" family of commands learned --cherry and --cherry-mark + options that can be used to view two diverged branches while omitting + or highlighting equivalent changes that appear on both sides of a + symmetric difference (e.g. "log --cherry A...B"). + + * A lazy "git merge" that didn't say what to merge used to be an error. + When run on a branch that has an upstream defined, however, the command + now merges from the configured upstream. + + * "git mergetool" learned how to drive "beyond compare 3" as well. + + * "git rerere forget" without pathspec used to forget all the saved + conflicts that relate to the current merge; it now requires you to + give it pathspecs. + + * "git rev-list --objects $revs -- $pathspec" now limits the objects listed + in its output properly with the pathspec, in preparation for narrow + clones. + + * "git push" with no parameters gives better advice messages when + "tracking" is used as the push.default semantics or there is no remote + configured yet. + + * A possible value to the "push.default" configuration variable, + 'tracking', gained a synonym that more naturally describes what it + does, 'upstream'. + + * "git rerere" learned a new subcommand "remaining" that is similar to + "status" and lists the paths that had conflicts which are known to + rerere, but excludes the paths that have already been marked as + resolved in the index from its output. "git mergetool" has been + updated to use this facility. + +Also contains various documentation updates. + + +Fixes since v1.7.4 +------------------ + +All of the fixes in the v1.7.4.X maintenance series are included in this +release, unless otherwise noted. + + * "git fetch" from a client that is mostly following the remote + needlessly told all of its refs to the server for both sides to + compute the set of objects that need to be transferred efficiently, + instead of stopping when the server heard enough. In a project with + many tags, this turns out to be extremely wasteful, especially over + the smart HTTP transport (sp/maint-{upload,fetch}-pack-stop-early~1). + + * "git fetch" run from a repository that uses the same repository as + its alternate object store as the repository it is fetching from + did not tell the server that it already has access to objects + reachable from the refs in their common alternate object store, + causing it to fetch unnecessary objects (jc/maint-fetch-alt). + + * "git remote add --mirror" created a configuration that is suitable for + doing both a mirror fetch and a mirror push at the same time, which + made little sense. We now warn and require the command line to specify + either --mirror=fetch or --mirror=push. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 72741ebda1..c6a5032912 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,10 +10,18 @@ Checklist (and a short version for the impatient): description (50 characters is the soft limit, see DISCUSSION in git-commit(1)), and should skip the full stop - the body should provide a meaningful commit message, which: - - uses the imperative, present tense: "change", - not "changed" or "changes". - - includes motivation for the change, and contrasts - its implementation with previous behaviour + . explains the problem the change tries to solve, iow, what + is wrong with the current code without the change. + . justifies the way the change solves the problem, iow, why + the result with the change is better. + . alternate solutions considered but discarded, if any. + - describe changes in imperative mood, e.g. "make xyzzy do frotz" + instead of "[This patch] makes xyzzy do frotz" or "[I] changed + xyzzy to do frotz", as if you are giving orders to the codebase + to change its behaviour. + - try to make sure your explanation can be understood without + external resources. Instead of giving a URL to a mailing list + archive, summarize the relevant points of the discussion. - add a "Signed-off-by: Your Name <you@example.com>" line to the commit message (or just use the option "-s" when committing) to confirm that you agree to the Developer's Certificate of Origin @@ -90,7 +98,10 @@ your commit head. Instead, always make a commit with complete commit message and generate a series of patches from your repository. It is a good discipline. -Describe the technical detail of the change(s). +Give an explanation for the change(s) that is detailed enough so +that people can judge if it is good thing to do, without reading +the actual patch text to determine how well the code does what +the explanation promises to do. If your description starts to get too long, that's a sign that you probably need to split up your commit to finer grained pieces. @@ -99,9 +110,8 @@ help reviewers check the patch, and future maintainers understand the code, are the most beautiful patches. Descriptions that summarise the point in the subject well, and describe the motivation for the change, the approach taken by the change, and if relevant how this -differs substantially from the prior version, can be found on Usenet -archives back into the late 80's. Consider it like good Netiquette, -but for code. +differs substantially from the prior version, are all good things +to have. Oh, another thing. I am picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped @@ -266,7 +276,7 @@ don't hide your real name. 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 +1. "Reported-by:" is used 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. @@ -598,4 +608,3 @@ following commands: Just make sure to disable line wrapping in the email client (GMail web interface will line wrap no matter what, so you need to use a real IMAP client). - diff --git a/Documentation/config.txt b/Documentation/config.txt index 4f1e979932..0906499e7d 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -62,7 +62,7 @@ Internal whitespace within a variable value is retained verbatim. The values following the equals sign in variable assign are all either a string, an integer, or a boolean. Boolean values may be given as yes/no, -0/1, true/false or on/off. Case is not significant in boolean values, when +1/0, true/false or on/off. Case is not significant in boolean values, when converting value to the canonical form using '--bool' type specifier; 'git config' will ensure that the output is "true" or "false". @@ -317,24 +317,26 @@ false), while all other repositories are assumed to be bare (bare = true). core.worktree:: - Set the path to the root of the work tree. + Set the path to the root of the working tree. This can be overridden by the GIT_WORK_TREE environment - variable and the '--work-tree' command line option. It can be - an absolute path or a relative path to the .git directory, - either specified by --git-dir or GIT_DIR, or automatically - discovered. - If --git-dir or GIT_DIR are specified but none of + variable and the '--work-tree' command line option. + The value can be an absolute path or relative to the path to + the .git directory, which is either specified by --git-dir + or GIT_DIR, or automatically discovered. + If --git-dir or GIT_DIR is specified but none of --work-tree, GIT_WORK_TREE and core.worktree is specified, - the current working directory is regarded as the root of the - work tree. + the current working directory is regarded as the top level + of your working tree. + Note that this variable is honored even when set in a configuration -file in a ".git" subdirectory of a directory, and its value differs +file in a ".git" subdirectory of a directory and its value differs from the latter directory (e.g. "/path/to/.git/config" has core.worktree set to "/different/path"), which is most likely a -misconfiguration. Running git commands in "/path/to" directory will +misconfiguration. Running git commands in the "/path/to" directory will still use "/different/path" as the root of the work tree and can cause -great confusion to the users. +confusion unless you know what you are doing (e.g. you are creating a +read-only snapshot of the same index to a location different from the +repository's usual working tree). core.logAllRefUpdates:: Enable the reflog. Updates to a ref <ref> is logged to the file @@ -440,8 +442,6 @@ for most projects as source code and other text files can still be delta compressed, but larger binary media files won't be. + Common unit suffixes of 'k', 'm', or 'g' are supported. -+ -Currently only linkgit:git-fast-import[1] honors this setting. core.excludesfile:: In addition to '.gitignore' (per-directory) and @@ -459,6 +459,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 @@ -507,6 +513,9 @@ core.whitespace:: part of the line terminator, i.e. with it, `trailing-space` does not trigger if the character before such a carriage-return is not a whitespace (not enabled by default). +* `tabwidth=<n>` tells how many character positions a tab occupies; this + is relevant for `indent-with-non-tab` and when git fixes `tab-in-indent` + errors. The default tab width is 8. Allowed values are 1 to 63. core.fsyncobjectfiles:: This boolean will enable 'fsync()' when writing object files. @@ -547,6 +556,12 @@ core.sparseCheckout:: Enable "sparse checkout" feature. See section "Sparse checkout" in linkgit:git-read-tree[1] for more information. +core.abbrev:: + Set the length object names are abbreviated to. If unspecified, + many commands abbreviate to 7 hexdigits, which may not be enough + for abbreviated object names to stay unique for sufficiently long + time. + add.ignore-errors:: add.ignoreErrors:: Tells 'git add' to continue adding files when some files cannot be @@ -599,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:: @@ -611,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 @@ -678,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 @@ -706,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 @@ -771,7 +787,8 @@ color.status.<slot>:: one of `header` (the header text of the status message), `added` or `updated` (files which are added but not committed), `changed` (files which are changed but not added in the index), - `untracked` (files which are not tracked by git), or + `untracked` (files which are not tracked by git), + `branch` (the current branch), or `nobranch` (the color the 'no branch' warning is shown in, defaulting to red). The values of these variables may be specified as in color.branch.<slot>. @@ -877,6 +894,15 @@ diff.wordRegex:: sequences that match the regular expression are "words", all other characters are *ignorable* whitespace. +fetch.recurseSubmodules:: + This option can be either set to a boolean value or to 'on-demand'. + Setting it to a boolean changes the behavior of fetch and pull to + unconditionally recurse into submodules when set to true or to not + recurse at all when set to false. When set to 'on-demand' (the default + value), fetch and pull will only recurse into a populated submodule + when its superproject retrieves a commit that updates the submodule's + reference. + fetch.unpackLimit:: If the number of objects fetched over the git native transfer is below this @@ -1074,6 +1100,12 @@ All gitcvs variables except for 'gitcvs.usecrlfattr' and is one of "ext" and "pserver") to make them apply only for the given access method. +grep.lineNumber:: + If set to true, enable '-n' option by default. + +grep.extendedRegexp:: + If set to true, enable '--extended-regexp' option by default. + gui.commitmsgwidth:: Defines how wide the commit message window is in the linkgit:git-gui[1]. "75" is the default. @@ -1100,7 +1132,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:: @@ -1529,11 +1561,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 @@ -1562,7 +1596,8 @@ push.default:: * `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. +* `upstream` - push the current branch to its upstream branch. +* `tracking` - deprecated synonym for `upstream`. * `current` - push the current branch to a branch of the same name. rebase.stat:: @@ -1735,6 +1770,7 @@ sendemail.to:: sendemail.smtpdomain:: sendemail.smtpserver:: sendemail.smtpserverport:: +sendemail.smtpserveroption:: sendemail.smtpuser:: sendemail.thread:: sendemail.validate:: @@ -1788,6 +1824,13 @@ submodule.<name>.update:: URL and other values found in the `.gitmodules` file. See linkgit:git-submodule[1] and linkgit:gitmodules[5] for details. +submodule.<name>.fetchRecurseSubmodules:: + This option can be used to control recursive fetching of this + submodule. It can be overridden by using the --[no-]recurse-submodules + command line option to "git fetch" and "git pull". + This setting will override that from in the linkgit:gitmodules[5] + file. + submodule.<name>.ignore:: Defines under what circumstances "git status" and the diff family show a submodule as modified. When set to "all", it will never be considered diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 3ac2beac62..c57460c03d 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -74,10 +74,13 @@ separate lines indicate the old and the new mode. combined diff format -------------------- -"git-diff-tree", "git-diff-files" and "git-diff" can take '-c' or -'--cc' option to produce 'combined diff'. For showing a merge commit -with "git log -p", this is the default format; you can force showing -full diff with the '-m' option. +Any diff-generating command can take the `-c` or `--cc` option to +produce a 'combined diff' when showing a merge. This is the default +format when showing merges with linkgit:git-diff[1] or +linkgit:git-show[1]. Note also that you can give the `-m' option to any +of these commands to force generation of diffs with individual parents +of a merge. + A 'combined diff' format looks like this: ------------ diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 5495344e61..c32105f1ed 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -72,6 +72,10 @@ endif::git-format-patch[] 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 are not counted for the parent directory, unless `--cumulative` is used. ++ +Note that the `--dirstat` option computes the changes while ignoring +the amount of pure code movements within a file. In other words, +rearranging lines in a file is not counted as much as other changes. --dirstat-by-file[=<limit>]:: Same as `--dirstat`, but counts changed files instead of lines. @@ -207,6 +211,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 +234,7 @@ eligible for being picked up as a possible source of a rename to another file. -M[<n>]:: +--find-renames[=<n>]:: ifndef::git-log[] Detect renames. endif::git-log[] @@ -237,13 +243,14 @@ ifdef::git-log[] For following files across renames while traversing history, see `--follow`. endif::git-log[] - If `n` is specified, it is a is a threshold on the similarity + If `n` is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the file's size). For example, `-M90%` means git should consider a delete/add pair to be a rename if more than 90% of the file hasn't changed. -C[<n>]:: +--find-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>`. @@ -282,8 +289,12 @@ ifndef::git-format-patch[] 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 e0ba8cc075..ae413e52a5 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 5ce1e72745..39d326abc6 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[] @@ -64,6 +64,34 @@ ifndef::git-pull[] downloaded. The default behavior for a remote may be specified with the remote.<name>.tagopt setting. See linkgit:git-config[1]. + +--recurse-submodules[=yes|on-demand|no]:: + This option controls if and under what conditions new commits of + populated submodules should be fetched too. It can be used as a + boolean option to completely disable recursion when set to 'no' or to + unconditionally recurse into all populated submodules when set to + 'yes', which is the default when this option is used without any + value. Use 'on-demand' to only recurse into a populated submodule + when the superproject retrieves a commit that updates the submodule's + reference to a commit that isn't already in the local submodule + clone. + +--no-recurse-submodules:: + Disable recursive fetching of submodules (this has the same effect as + using the '--recurse-submodules=no' option). + +--submodule-prefix=<path>:: + Prepend <path> to paths printed in informative messages + such as "Fetching submodule foo". This option is used + internally when recursing over submodules. + +--recurse-submodules-default=[yes|on-demand]:: + This option is used internally to temporarily provide a + non-negative default value for the --recurse-submodules + option. All other methods of configuring fetch's submodule + recursion (such as settings in linkgit:gitmodules[5] and + linkgit:git-config[1]) override this option, as does + specifying --[no-]recurse-submodules directly. endif::git-pull[] -u:: diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 54aaaeb41b..35cb5d3f64 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -134,6 +134,8 @@ subdirectories. If some files could not be added because of errors indexing them, do not abort the operation, but continue adding the others. The command shall still exit with non-zero status. + The configuration variable `add.ignoreErrors` can be set to + true to make this the default behaviour. --ignore-missing:: This option can only be used together with --dry-run. By using @@ -333,7 +335,7 @@ 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 +For example, introducing 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. @@ -378,14 +380,6 @@ linkgit:git-mv[1] linkgit:git-commit[1] linkgit:git-update-index[1] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 51297d09ec..6b1b5af64e 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -173,9 +173,9 @@ aborts in the middle. You can recover from this in one of two ways: the index file to bring it into a state that the patch should have produced. Then run the command with the '--resolved' option. -The command refuses to process new mailboxes while the `.git/rebase-apply` -directory exists, so if you decide to start over from scratch, -run `rm -f -r .git/rebase-apply` before running the command with mailbox +The command refuses to process new mailboxes until the current +operation is finished, so if you decide to start over from scratch, +run `git am --abort` before running the command with mailbox names. Before any patches are applied, ORIG_HEAD is set to the tip of the @@ -189,15 +189,6 @@ SEE ALSO -------- linkgit:git-apply[1]. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt index 0590eec056..9eb75c37da 100644 --- a/Documentation/git-annotate.txt +++ b/Documentation/git-annotate.txt @@ -27,10 +27,6 @@ SEE ALSO -------- linkgit:git-blame[1] -AUTHOR ------- -Written by Ryan Anderson <ryan@michonline.com>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 881652f490..afd2c9ae59 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -22,7 +22,7 @@ DESCRIPTION ----------- Reads the supplied diff output (i.e. "a patch") and applies it to files. With the `--index` option the patch is also applied to the index, and -with the `--cache` option the patch is only applied to the index. +with the `--cached` option the patch is only applied to the index. Without these options, the command applies the patch only to files, and does not require them to be in a git repository. @@ -246,20 +246,10 @@ If `--index` is not specified, then the submodule commits in the patch are ignored and only the absence or presence of the corresponding subdirectory is checked and (if possible) updated. - SEE ALSO -------- linkgit:git-am[1]. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index 4f358c8d6c..f4504ba9bf 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -107,14 +107,6 @@ OPTIONS Archive/branch identifier in a format that `tla log` understands. -Author ------- -Written by Martin Langhoff <martin@catalyst.net.nz>. - -Documentation --------------- -Documentation by Junio C Hamano, Martin Langhoff and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index bf5037ab2a..9c750e2444 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -98,7 +98,8 @@ tar.umask:: tar archive entries. The default is 0002, which turns off the world write bit. The special value "user" indicates that the archiving user's umask will be used instead. See umask(2) for - details. + details. If `--remote` is used then only the configuration of + the remote repository takes effect. ATTRIBUTES ---------- @@ -153,14 +154,6 @@ SEE ALSO -------- linkgit:gitattributes[5] -Author ------- -Written by Franck Bui-Huu and Rene Scharfe. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index c39d957c3a..7b7bafba0c 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -241,7 +241,12 @@ exit(3) manual page), as the value is chopped with "& 0377". The special exit code 125 should be used when the current source code cannot be tested. If the script exits with this code, the current -revision will be skipped (see `git bisect skip` above). +revision will be skipped (see `git bisect skip` above). 125 was chosen +as the highest sensible value to use for this purpose, because 126 and 127 +are used by POSIX shells to signal specific error status (127 is for +command not found, 126 is for command found but not executable---these +details do not matter, as they are normal errors in the script, as far as +"bisect run" is concerned). You may often find that during a bisect session you want to have temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a @@ -274,61 +279,68 @@ $ git bisect start HEAD origin -- # HEAD is bad, origin is good $ git bisect run make test # "make test" builds and tests ------------ -* Automatically bisect a broken test suite: +* Automatically bisect a broken test case: + ------------ $ cat ~/test.sh #!/bin/sh -make || exit 125 # this skips broken builds -make test # "make test" runs the test suite -$ git bisect start v1.3 v1.1 -- # v1.3 is bad, v1.1 is good +make || exit 125 # this skips broken builds +~/check_test_case.sh # does the test case pass? +$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 $ git bisect run ~/test.sh ------------ + Here we use a "test.sh" custom script. In this script, if "make" fails, we skip the current commit. +"check_test_case.sh" should "exit 0" if the test case passes, +and "exit 1" otherwise. + -It is safer to use a custom script outside the repository to prevent -interactions between the bisect, make and test processes and the -script. -+ -"make test" should "exit 0", if the test suite passes, and -"exit 1" otherwise. +It is safer if both "test.sh" and "check_test_case.sh" are +outside the repository to prevent interactions between the bisect, +make and test processes and the scripts. -* Automatically bisect a broken test case: +* Automatically bisect with temporary modifications (hot-fix): + ------------ $ cat ~/test.sh #!/bin/sh -make || exit 125 # this skips broken builds -~/check_test_case.sh # does the test case passes ? -$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 -$ git bisect run ~/test.sh + +# tweak the working tree by merging the hot-fix branch +# and then attempt a build +if git merge --no-commit hot-fix && + make +then + # run project specific test and report its status + ~/check_test_case.sh + status=$? +else + # tell the caller this is untestable + status=125 +fi + +# undo the tweak to allow clean flipping to the next commit +git reset --hard + +# return control +exit $status ------------ + -Here "check_test_case.sh" should "exit 0" if the test case passes, -and "exit 1" otherwise. -+ -It is safer if both "test.sh" and "check_test_case.sh" scripts are -outside the repository to prevent interactions between the bisect, -make and test processes and the scripts. +This applies modifications from a hot-fix branch before each test run, +e.g. in case your build or test environment changed so that older +revisions may need a fix which newer ones have already. (Make sure the +hot-fix branch is based off a commit which is contained in all revisions +which you are bisecting, so that the merge does not pull in too much, or +use `git cherry-pick` instead of `git merge`.) -* Automatically bisect a broken test suite: +* Automatically bisect a broken test case: + ------------ $ git bisect start HEAD HEAD~10 -- # culprit is among the last 10 $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh" ------------ + -Does the same as the previous example, but on a single line. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation -------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +This shows that you can do without a run script if you write the test +on a single line. SEE ALSO -------- diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index a27f43950f..c4d1ff86c9 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. @@ -194,10 +198,6 @@ SEE ALSO -------- linkgit:git-annotate[1] -AUTHOR ------- -Written by Junio C Hamano <gitster@pobox.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 1940256930..c50f189827 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 @@ -230,14 +232,6 @@ linkgit:git-remote[1], link:user-manual.html#what-is-a-branch[``Understanding history: What is a branch?''] in the Git User's Manual. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 6266a3a602..92b01ec25d 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -59,7 +59,7 @@ unbundle <file>:: <git-rev-list-args>:: A list of arguments, acceptable to 'git rev-parse' and - 'git rev-list' (and containg a named ref, see SPECIFYING REFERENCES + 'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES below), that specifies the specific objects and references to transport. For example, `master{tilde}10..master` causes the current master reference to be packaged along with all objects @@ -201,10 +201,6 @@ You can also see what references it offers: $ git ls-remote mybundle ---------------- -Author ------- -Written by Mark Levedahl <mdl123@verizon.net> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 544ba7ba21..2fb95bbd19 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -100,14 +100,6 @@ for each object specified on stdin that does not exist in the repository: <object> SP missing LF ------------ -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 50824e3a2d..30eca6cee6 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -86,15 +86,6 @@ SEE ALSO -------- linkgit:gitattributes[5]. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by James Bowes. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 0c0a9c14bc..4d33e7be0f 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -172,18 +172,6 @@ $ git checkout-index --prefix=.merged- Makefile This will check out the currently cached copy of `Makefile` into the file `.merged-Makefile`. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - - -Documentation --------------- -Documentation by David Greaves, -Junio C Hamano and the git-list <git@vger.kernel.org>. - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 22d36114df..1063f69023 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -9,6 +9,7 @@ SYNOPSIS -------- [verse] 'git checkout' [-q] [-f] [-m] [<branch>] +'git checkout' [-q] [-f] [-m] [--detach] [<commit>] 'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... 'git checkout' --patch [<tree-ish>] [--] [<paths>...] @@ -22,9 +23,10 @@ branch. 'git checkout' [<branch>]:: 'git checkout' -b|-B <new_branch> [<start point>]:: +'git checkout' [--detach] [<commit>]:: This form switches branches by updating the index, working - tree, and HEAD to reflect the specified branch. + tree, and HEAD to reflect the specified branch or commit. + If `-b` is given, a new branch is created as if linkgit:git-branch[1] were called and then checked out; in this case you can @@ -98,7 +100,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 @@ -115,6 +117,13 @@ explicitly give a name with '-b' in such a case. Create the new branch's reflog; see linkgit:git-branch[1] for details. +--detach:: + Rather than checking out a branch to work on it, check out a + commit for inspection and discardable experiments. + This is the default behavior of "git checkout <commit>" when + <commit> is not a branch name. See the "DETACHED HEAD" section + below for details. + --orphan:: Create a new 'orphan' branch, named <new_branch>, started from <start_point> and switch to it. The first commit made on this @@ -204,42 +213,140 @@ leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. -Detached HEAD +DETACHED HEAD ------------- +HEAD normally refers to a named branch (e.g. 'master'). Meanwhile, each +branch refers to a specific commit. Let's look at a repo with three +commits, one of them tagged, and with branch 'master' checked out: + +------------ + HEAD (refers to branch 'master') + | + v +a---b---c branch 'master' (refers to commit 'c') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ -It is sometimes useful to be able to 'checkout' a commit that is -not at the tip of one of your branches. The most obvious -example is to check out the commit at a tagged official release -point, like this: +When a commit is created in this state, the branch is updated to refer to +the new commit. Specifically, 'git commit' creates a new commit 'd', whose +parent is commit 'c', and then updates branch 'master' to refer to new +commit 'd'. HEAD still refers to branch 'master' and so indirectly now refers +to commit 'd': ------------ -$ git checkout v2.6.18 +$ edit; git add; git commit + + HEAD (refers to branch 'master') + | + v +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') ------------ -Earlier versions of git did not allow this and asked you to -create a temporary branch using the `-b` option, but starting from -version 1.5.0, the above command 'detaches' your HEAD from the -current branch and directly points at the commit named by the tag -(`v2.6.18` in the example above). +It is sometimes useful to be able to checkout a commit that is not at +the tip of any named branch, or even to create a new commit that is not +referenced by a named branch. Let's look at what happens when we +checkout commit 'b' (here we show two ways this may be done): -You can use all git commands while in this state. You can use -`git reset --hard $othercommit` to further move around, for -example. You can make changes and create a new commit on top of -a detached HEAD. You can even create a merge by using `git -merge $othercommit`. +------------ +$ git checkout v2.0 # or +$ git checkout master^^ + + HEAD (refers to commit 'b') + | + v +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ -The state you are in while your HEAD is detached is not recorded -by any branch (which is natural --- you are not on any branch). -What this means is that you can discard your temporary commits -and merges by switching back to an existing branch (e.g. `git -checkout master`), and a later `git prune` or `git gc` would -garbage-collect them. If you did this by mistake, you can ask -the reflog for HEAD where you were, e.g. +Notice that regardless of which checkout command we use, HEAD now refers +directly to commit 'b'. This is known as being in detached HEAD state. +It means simply that HEAD refers to a specific commit, as opposed to +referring to a named branch. Let's see what happens when we create a commit: ------------ -$ git log -g -2 HEAD +$ edit; git add; git commit + + HEAD (refers to commit 'e') + | + v + e + / +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ + +There is now a new commit 'e', but it is referenced only by HEAD. We can +of course add yet another commit in this state: + +------------ +$ edit; git add; git commit + + HEAD (refers to commit 'f') + | + v + e---f + / +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') +------------ + +In fact, we can perform all the normal git operations. But, let's look +at what happens when we then checkout master: + +------------ +$ git checkout master + + HEAD (refers to branch 'master') + e---f | + / v +a---b---c---d branch 'master' (refers to commit 'd') + ^ + | + tag 'v2.0' (refers to commit 'b') ------------ +It is important to realize that at this point nothing refers to commit +'f'. Eventually commit 'f' (and by extension commit 'e') will be deleted +by the routine git garbage collection process, unless we create a reference +before that happens. If we have not yet moved away from commit 'f', +any of these will create a reference to it: + +------------ +$ git checkout -b foo <1> +$ git branch foo <2> +$ git tag foo <3> +------------ + +<1> creates a new branch 'foo', which refers to commit 'f', and then +updates HEAD to refer to branch 'foo'. In other words, we'll no longer +be in detached HEAD state after this command. + +<2> similarly creates a new branch 'foo', which refers to commit 'f', +but leaves HEAD detached. + +<3> creates a new tag 'foo', which refers to commit 'f', +leaving HEAD detached. + +If we have moved away from commit 'f', then we must first recover its object +name (typically by using git reflog), and then we can create a reference to +it. For example, to see the last two commits to which HEAD referred, we +can use either of these commands: + +------------ +$ git reflog -2 HEAD # or +$ git log -g -2 HEAD +------------ EXAMPLES -------- @@ -315,15 +422,6 @@ $ edit frotz $ git add frotz ------------ - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 73008705eb..01db83039f 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -16,6 +16,25 @@ Given one or more existing commits, apply the change each one introduces, recording a new commit for each. This requires your working tree to be clean (no modifications from the HEAD commit). +When it is not obvious how to apply a change, the following +happens: + +1. The current branch and `HEAD` pointer stay at the last commit + successfully made. +2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that + introduced the change that is difficult to apply. +3. Paths in which the change applied cleanly are updated both + in the index file and in your working tree. +4. For conflicting paths, the index file records up to three + versions, as described in the "TRUE MERGE" section of + linkgit:git-merge[1]. The working tree files will include + a description of the conflict bracketed by the usual + conflict markers `<<<<<<<` and `>>>>>>>`. +5. No other modifications are made. + +See linkgit:git-merge[1] for some hints on resolving such +conflicts. + OPTIONS ------- <commit>...:: @@ -79,6 +98,16 @@ effect to your index in a row. cherry-pick'ed commit, then a fast forward to this commit will be performed. +--strategy=<strategy>:: + Use the given merge strategy. Should only be used once. + See the MERGE STRATEGIES section in linkgit:git-merge[1] + for details. + +-X<option>:: +--strategy-option=<option>:: + Pass the merge strategy-specific option through to the + merge strategy. See linkgit:git-merge[1] for details. + EXAMPLES -------- git cherry-pick master:: @@ -120,13 +149,27 @@ git rev-list --reverse master \-- README | git cherry-pick -n --stdin:: so the result can be inspected and made into a single new commit if suitable. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. +The following sequence attempts to backport a patch, bails out because +the code the patch applies to has changed too much, and then tries +again, this time exercising more care about matching up context lines. + +------------ +$ git cherry-pick topic^ <1> +$ git diff <2> +$ git reset --merge ORIG_HEAD <3> +$ git cherry-pick -Xpatience topic^ <4> +------------ +<1> apply the change that would be shown by `git show topic^`. +In this example, the patch does not apply cleanly, so +information about the conflict is written to the index and +working tree and no new commit results. +<2> summarize changes to be reconciled +<3> cancel the cherry-pick. In other words, return to the +pre-cherry-pick state, preserving any local modifications you had in +the working tree. +<4> try to apply the change introduced by `topic^` again, +spending extra time to avoid mistakes based on incorrectly matching +context lines. SEE ALSO -------- diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index fed115acd0..79448c505b 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -63,14 +63,6 @@ SEE ALSO -------- linkgit:git-patch-id[1] -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-citool.txt b/Documentation/git-citool.txt index fb2753c97e..6e5c8126f5 100644 --- a/Documentation/git-citool.txt +++ b/Documentation/git-citool.txt @@ -19,14 +19,6 @@ to the less interactive 'git commit' program. 'git citool' is actually a standard alias for `git gui citool`. See linkgit:git-gui[1] for more details. -Author ------- -Written by Shawn O. Pearce <spearce@spearce.org>. - -Documentation --------------- -Documentation by Shawn O. Pearce <spearce@spearce.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 60e38e6e27..974e04ef1a 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -61,12 +61,6 @@ OPTIONS Remove only files ignored by git. This may be useful to rebuild everything from scratch, but keep manually created files. - -Author ------- -Written by Pavel Roskin <proski@gnu.org> - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index ab7293351d..86eb4c9368 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -12,7 +12,9 @@ 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>] + [--separate-git-dir|-L <git dir>] + [--depth <depth>] [--recursive|--recurse-submodules] [--] <repository> + [<directory>] DESCRIPTION ----------- @@ -131,7 +133,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 +169,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 @@ -174,6 +177,15 @@ objects from the source repository into a pack in the cloned repository. repository does not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) +-L=<git dir>:: +--separate-git-dir=<git dir>:: + Instead of placing the cloned repository where it is supposed + to be, place the cloned repository at the specified directory, + then make a filesytem-agnostic git symbolic link to there. + The result is git repository can be separated from working + tree. + + <repository>:: The (possibly remote) repository to clone from. See the <<URLS,URLS>> section below for more information on specifying @@ -234,17 +246,6 @@ $ git clone --bare -l -s /pub/scm/.../torvalds/linux-2.6.git \ /pub/scm/.../me/subsys-2.6.git ------------ - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 5dcf4278fc..f524d76019 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -93,15 +93,6 @@ SEE ALSO -------- linkgit:git-write-tree[1] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index ec7b577b85..d0534b8c05 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,10 +70,24 @@ 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. - This also renews the author timestamp. + When used with -C/-c/--amend options, or when committing after a + a conflicting cherry-pick, declare that the authorship of the + resulting commit now belongs of the committer. This also renews + the author timestamp. --short:: When doing a dry-run, give the output in the short-format. See @@ -201,10 +215,11 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) -u[<mode>]:: --untracked-files[=<mode>]:: - Show untracked files (Default: 'all'). + Show untracked files. + -The mode parameter is optional, and is used to specify -the handling of untracked files. +The mode parameter is optional (defaults to 'all'), and is used to +specify the handling of untracked files; when -u is not used, the +default is 'normal', i.e. show untracked files and directories. + The possible options are: + @@ -212,9 +227,8 @@ The possible options are: - 'normal' - Shows untracked files and directories - 'all' - Also shows individual files in untracked directories. + -See linkgit:git-config[1] for configuration variable -used to change the default for when the option is not -specified. +The default can be changed using the status.showUntrackedFiles +configuration variable documented in linkgit:git-config[1]. -v:: --verbose:: @@ -383,12 +397,6 @@ linkgit:git-mv[1], linkgit:git-merge[1], linkgit:git-commit-tree[1] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <gitster@pobox.com> - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 543dd64a46..8804de327f 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -336,15 +336,6 @@ echo "${WS}your whitespace color or blue reverse${RESET}" include::config.txt[] - -Author ------- -Written by Johannes Schindelin <Johannes.Schindelin@gmx.de> - -Documentation --------------- -Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index 6bc1c21e62..a73933a931 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -25,15 +25,6 @@ OPTIONS and number of objects that can be removed by running `git prune-packed`. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index b2696efae9..ad93a3e84e 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -112,14 +112,6 @@ $ cd ~/project_cvs_checkout $ git cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git cvsexportcommit -c -p -v ------------ -Author ------- -Written by Martin Langhoff <martin@catalyst.net.nz> and others. - -Documentation --------------- -Documentation by Martin Langhoff <martin@catalyst.net.nz> and others. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index 608cd63fc3..6695ab3b4b 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -217,15 +217,6 @@ more stable in practice: * cvs2git (part of cvs2svn), `http://cvs2svn.tigris.org` * parsecvs, `http://cgit.freedesktop.org/~keithp/parsecvs` -Author ------- -Written by Matthias Urlichs <smurf@smurf.noris.de>, with help from -various participants of the git-list <git@vger.kernel.org>. - -Documentation --------------- -Documentation by Matthias Urlichs <smurf@smurf.noris.de>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index f4472c61db..88d814af0e 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -391,22 +391,6 @@ Dependencies ------------ 'git-cvsserver' depends on DBD::SQLite. -Copyright and Authors ---------------------- - -This program is copyright The Open University UK - 2006. - -Authors: - -- Martyn Smith <martyn@catalyst.net.nz> -- Martin Langhoff <martin@catalyst.net.nz> - -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>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 2f0ddf6fe8..ebd13be72e 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -78,13 +78,15 @@ 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 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>:: @@ -277,17 +279,6 @@ that connected to it, if the IP address is available. REMOTE_ADDR will be available in the environment of hooks called when services are performed. - - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org>, YOSHIFUJI Hideaki -<yoshfuji@linux-ipv6.org> and the git-list <git@vger.kernel.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 7ef9d51577..039cce2e98 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 @@ -156,17 +156,6 @@ selected and output. Here fewest commits different is defined as the number of commits which would be shown by `git log tag..input` will be the smallest number of commits possible. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org>, but somewhat -butchered by Junio C Hamano <gitster@pobox.com>. Later significantly -updated by Shawn Pearce <spearce@spearce.org>. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index 9cd8ccef37..8d481948bd 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -46,15 +46,6 @@ omit diff output for unmerged entries and just show "Unmerged". include::diff-format.txt[] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 162cb741b3..6d18486402 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -116,15 +116,6 @@ tell which file is in which state, since the "has been updated" ones show a valid sha1, and the "not in sync with the index" ones will always have the special all-zero sha1. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index a7e37b875f..4e5f127efa 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -162,15 +162,6 @@ in case you care). include::diff-format.txt[] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index dd1fb32786..f8d0819113 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>...]:: @@ -33,6 +38,8 @@ directories. This behavior can be forced by --no-index. commit relative to the named <commit>. Typically you would want comparison with the latest commit, so if you do not give <commit>, it defaults to HEAD. + If HEAD does not exist (e.g. unborned branches) and + <commit> is not given, it shows all staged changes. --staged is a synonym of --cached. 'git diff' [--options] <commit> [--] [<path>...]:: @@ -167,14 +174,6 @@ linkgit:gitdiffcore[7], linkgit:git-format-patch[1], linkgit:git-apply[1] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 5738432111..590f410abf 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 ------- @@ -30,8 +31,8 @@ OPTIONS --tool=<tool>:: Use the diff tool specified by <tool>. Valid merge tools are: - kdiff3, kompare, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, - ecmerge, diffuse, opendiff, p4merge and araxis. + araxis, bc3, diffuse, emerge, ecmerge, gvimdiff, kdiff3, + kompare, meld, opendiff, p4merge, tkdiff, vimdiff and xxdiff. + If a diff tool is not specified, 'git difftool' will use the configuration variable `diff.tool`. If the @@ -108,15 +109,6 @@ linkgit:git-mergetool[1]:: linkgit:git-config[1]:: Get and set repository or global options - -AUTHOR ------- -Written by David Aguilar <davvid@gmail.com>. - -Documentation --------------- -Documentation by David Aguilar and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index e05b686b1e..781bd6edc3 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -135,15 +135,6 @@ Since 'git fast-import' cannot tag trees, you will not be able to export the linux-2.6.git repository completely, as it contains a tag referencing a tree instead of a commit. - -Author ------- -Written by Johannes E. Schindelin <johannes.schindelin@gmx.de>. - -Documentation --------------- -Documentation by Johannes E. Schindelin <johannes.schindelin@gmx.de>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 4349d6a9a6..249249aac7 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -78,8 +78,12 @@ OPTIONS set of marks. If a mark is defined to different values, the last file wins. +--import-marks-if-exists=<file>:: + Like --import-marks but instead of erroring out, silently + skips the file if it does not exist. + --relative-marks:: - After specifying --relative-marks= the paths specified + After specifying --relative-marks the paths specified with --import-marks= and --export-marks= are relative to an internal directory in the current repository. In git-fast-import this means that the paths are relative @@ -89,9 +93,14 @@ OPTIONS --no-relative-marks:: Negates a previous --relative-marks. Allows for combining relative and non-relative marks by interweaving - --(no-)-relative-marks= with the --(import|export)-marks= + --(no-)-relative-marks with the --(import|export)-marks= options. +--cat-blob-fd=<fd>:: + Specify the file descriptor that will be written to + when the `cat-blob` command is encountered in the stream. + The default behaviour is to write to `stdout`. + --export-pack-edges=<file>:: After creating a packfile, print a line of data to <file> listing the filename of the packfile and the last @@ -187,7 +196,8 @@ especially when a higher level language such as Perl, Python or Ruby is being used. fast-import is very strict about its input. Where we say SP below we mean -*exactly* one space. Likewise LF means one (and only one) linefeed. +*exactly* one space. Likewise LF means one (and only one) linefeed +and HT one (and only one) horizontal tab. Supplying additional whitespace characters will cause unexpected results, such as branch names or file names with leading or trailing spaces in their name, or early termination of fast-import when it encounters @@ -320,6 +330,16 @@ and control the current import process. More detailed discussion standard output. This command is optional and is not needed to perform an import. +`cat-blob`:: + Causes fast-import to print a blob in 'cat-file --batch' + format to the file descriptor set with `--cat-blob-fd` or + `stdout` if unspecified. + +`ls`:: + Causes fast-import to print a line describing a directory + entry in 'ls-tree' format to the file descriptor set with + `--cat-blob-fd` or `stdout` if unspecified. + `feature`:: Require that fast-import supports the specified feature, or abort if it does not. @@ -532,6 +552,8 @@ The value of `<path>` must be in canonical form. That is it must not: * contain the special component `.` or `..` (e.g. `foo/./bar` and `foo/../bar` are invalid). +The root of the tree can be represented by an empty string as `<path>`. + It is recommended that `<path>` always be encoded using UTF-8. `filedelete` @@ -876,6 +898,82 @@ Placing a `progress` command immediately after a `checkpoint` will inform the reader when the `checkpoint` has been completed and it can safely access the refs that fast-import updated. +`cat-blob` +~~~~~~~~~~ +Causes fast-import to print a blob to a file descriptor previously +arranged with the `--cat-blob-fd` argument. The command otherwise +has no impact on the current import; its main purpose is to +retrieve blobs that may be in fast-import's memory but not +accessible from the target repository. + +.... + 'cat-blob' SP <dataref> LF +.... + +The `<dataref>` can be either a mark reference (`:<idnum>`) +set previously or a full 40-byte SHA-1 of a Git blob, preexisting or +ready to be written. + +Output uses the same format as `git cat-file --batch`: + +==== + <sha1> SP 'blob' SP <size> LF + <contents> LF +==== + +This command can be used anywhere in the stream that comments are +accepted. In particular, the `cat-blob` command can be used in the +middle of a commit but not in the middle of a `data` command. + +`ls` +~~~~ +Prints information about the object at a path to a file descriptor +previously arranged with the `--cat-blob-fd` argument. This allows +printing a blob from the active commit (with `cat-blob`) or copying a +blob or tree from a previous commit for use in the current one (with +`filemodify`). + +The `ls` command can be used anywhere in the stream that comments are +accepted, including the middle of a commit. + +Reading from the active commit:: + This form can only be used in the middle of a `commit`. + The path names a directory entry within fast-import's + active commit. The path must be quoted in this case. ++ +.... + 'ls' SP <path> LF +.... + +Reading from a named tree:: + The `<dataref>` can be a mark reference (`:<idnum>`) or the + full 40-byte SHA-1 of a Git tag, commit, or tree object, + preexisting or waiting to be written. + The path is relative to the top level of the tree + named by `<dataref>`. ++ +.... + 'ls' SP <dataref> SP <path> LF +.... + +See `filemodify` above for a detailed description of `<path>`. + +Output uses the same format as `git ls-tree <tree> {litdd} <path>`: + +==== + <mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF +==== + +The <dataref> represents the blob, tree, or commit object at <path> +and can be used in later 'cat-blob', 'filemodify', or 'ls' commands. + +If there is no file or subtree at that path, 'git fast-import' will +instead report + +==== + missing SP <path> LF +==== + `feature` ~~~~~~~~~ Require that fast-import supports the specified feature, or abort if @@ -902,12 +1000,22 @@ import-marks:: second, an --import-marks= command-line option overrides any "feature import-marks" command in the stream. +cat-blob:: +ls:: + Require that the backend support the 'cat-blob' or 'ls' command. + Versions of fast-import not supporting the specified command + will exit with a message indicating so. + This lets the import error out early with a clear message, + rather than wasting time on the early part of an import + before the unsupported command is detected. + notes:: Require that the backend support the 'notemodify' (N) subcommand to the 'commit' command. Versions of fast-import not supporting notes will exit with a message indicating so. + `option` ~~~~~~~~ Processes the specified option so that git fast-import behaves in a @@ -933,6 +1041,7 @@ not be passed as option: * date-format * import-marks * export-marks +* cat-blob-fd * force Crash Reports @@ -1233,14 +1342,13 @@ and lazy loading of subtrees, allows fast-import to efficiently import projects with 2,000+ branches and 45,114+ files in a very limited memory footprint (less than 2.7 MiB per active branch). - -Author ------- -Written by Shawn O. Pearce <spearce@spearce.org>. - -Documentation --------------- -Documentation by Shawn O. Pearce <spearce@spearce.org>. +Signals +------- +Sending *SIGUSR1* to the 'git fast-import' process ends the current +packfile early, simulating a `checkpoint` command. The impatient +operator can use this facility to peek at the objects and refs from an +import in progress, at the cost of some added running time and worse +compression. GIT --- diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 4a8487c154..48d4bf6d68 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -90,15 +90,6 @@ OPTIONS $GIT_DIR (e.g. "HEAD", "refs/heads/master"). When unspecified, update from all heads the remote side has. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index d159e88292..60ac8d26eb 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -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 @@ -34,7 +34,7 @@ pointed by remote tags that it does not yet have, then fetch those missing tags. If the other end has tags that point at branches you are not interested in, you will not get them. -'git fetch' can fetch from either a single named repository, or +'git fetch' can fetch from either a single named repository, or from several repositories at once if <group> is given and there is a remotes.<group> entry in the configuration file. (See linkgit:git-config[1]). @@ -76,20 +76,19 @@ The `pu` branch will be updated even if it is does not fast-forward, because it is prefixed with a plus sign; `tmp` will not be. +BUGS +---- +Using --recurse-submodules can only fetch new commits in already checked +out submodules right now. When e.g. upstream added a new submodule in the +just fetched commits of the superproject the submodule itself can not be +fetched, making it impossible to check out that submodule later without +having to do a fetch again. This is expected to be fixed in a future git +version. + SEE ALSO -------- linkgit:git-pull[1] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <gitster@pobox.com> - -Documentation -------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 796e7489ff..9dc1f2a947 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -361,7 +361,7 @@ git filter-branch --index-filter \ 'git ls-files -s | sed "s-\t\"*-&newsubdir/-" | GIT_INDEX_FILE=$GIT_INDEX_FILE.new \ git update-index --index-info && - mv $GIT_INDEX_FILE.new $GIT_INDEX_FILE' HEAD + mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' HEAD --------------------------------------------------------------- @@ -405,16 +405,6 @@ warned. (or if your git-gc is not new enough to support arguments to `\--prune`, use `git repack -ad; git prune` instead). - -Author ------- -Written by Petr "Pasky" Baudis <pasky@suse.cz>, -and the git list <git@vger.kernel.org> - -Documentation --------------- -Documentation by Petr Baudis and the git list. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 302f56b889..32aff954a2 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 synonym for 20. merge.summary:: Synonym to `merge.log`; this is deprecated and will be removed in @@ -63,15 +67,6 @@ SEE ALSO -------- linkgit:git-merge[1] - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index fac1cf55e5..152e695c81 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -123,7 +123,7 @@ EXAMPLES -------- An example directly producing formatted text. Show the most recent -3 tagged commits:: +3 tagged commits: ------------ #!/bin/sh @@ -140,7 +140,7 @@ Ref: %(*refname) A simple example showing the use of shell eval on the output, -demonstrating the use of --shell. List the prefixes of all heads:: +demonstrating the use of --shell. List the prefixes of all heads: ------------ #!/bin/sh @@ -154,7 +154,7 @@ done A bit more elaborate report on tags, demonstrating that the format -may be an entire script:: +may be an entire script: ------------ #!/bin/sh @@ -204,3 +204,15 @@ eval=`git for-each-ref --shell --format="$fmt" \ refs/tags` eval "$eval" ------------ + +Author +------ +Written by Junio C Hamano <gitster@pobox.com>. + +Documentation +------------- +Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index a00b783fe5..a5525e9aa8 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -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>:: @@ -278,15 +278,6 @@ SEE ALSO -------- linkgit:git-am[1], linkgit:git-send-email[1] - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.txt index 965a8279c1..90ebb8a594 100644 --- a/Documentation/git-fsck-objects.txt +++ b/Documentation/git-fsck-objects.txt @@ -15,3 +15,7 @@ DESCRIPTION This is a synonym for linkgit:git-fsck[1]. Please refer to the documentation of that command. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 86f9b2bf91..c9ede794b0 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -140,14 +140,6 @@ GIT_INDEX_FILE:: GIT_ALTERNATE_OBJECT_DIRECTORIES:: used to specify additional object database roots (usually unset) -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index a01eef6763..4966cb5784 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). @@ -151,10 +151,6 @@ linkgit:git-reflog[1] linkgit:git-repack[1] linkgit:git-rerere[1] -Author ------- -Written by Shawn O. Pearce <spearce@spearce.org> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index 790af9573b..8035736c96 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -22,15 +22,6 @@ return code of 1. This can happen if <tarfile> had not been created using 'git archive' or if the first parameter of 'git archive' had been a tree ID instead of a commit ID or tag. - -Author ------- -Written by Rene Scharfe <rene.scharfe@lsrfire.ath.cx> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index dab0a78fa8..d7523b3e45 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -31,6 +31,16 @@ Look for specified patterns in the tracked files in the work tree, blobs registered in the index file, or blobs in given tree objects. +CONFIGURATION +------------- + +grep.lineNumber:: + If set to true, enable '-n' option by default. + +grep.extendedRegexp:: + If set to true, enable '--extended-regexp' option by default. + + OPTIONS ------- --cached:: @@ -93,6 +103,7 @@ OPTIONS as a regex). -n:: +--line-number:: Prefix the line number to matching lines. -l:: @@ -203,16 +214,6 @@ git grep --all-match -e NODE -e Unexpected:: Looks for a line that has `NODE` or `Unexpected` in files that have lines that match both. -Author ------- -Originally written by Linus Torvalds <torvalds@osdl.org>, later -revamped by Junio C Hamano. - - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index 2563710b56..32a833e0ae 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -121,14 +121,6 @@ or or browsed online at http://repo.or.cz/w/git-gui.git/[]. -Author ------- -Written by Shawn O. Pearce <spearce@spearce.org>. - -Documentation --------------- -Documentation by Shawn O. Pearce <spearce@spearce.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 51edeecbe5..4b0a502e8e 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -53,14 +53,6 @@ OPTIONS conversion. If the file is read from standard input then this is always implied, unless the --path option is given. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index eccd0ffd38..42aa2b0c01 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -171,17 +171,6 @@ $ git config --global web.browser firefox as they are probably more user specific than repository specific. See linkgit:git-config[1] for more information about this. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> and the git-list -<git@vger.kernel.org>. - -Documentation -------------- -Initial documentation was part of the linkgit:git[1] man page. -Christian Couder <chriscool@tuxfamily.org> extracted and rewrote it a -little. Maintenance is done by the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-http-fetch.txt b/Documentation/git-http-fetch.txt index d91cb7ff85..fefa752198 100644 --- a/Documentation/git-http-fetch.txt +++ b/Documentation/git-http-fetch.txt @@ -43,14 +43,6 @@ commit-id:: Verify that everything reachable from target is fetched. Used after an earlier fetch is interrupted. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index ddf7a18dc4..82ae34b9b8 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -91,15 +91,6 @@ With '--force', the fast-forward check is disabled for all refs. Optionally, a <ref> parameter can be prefixed with a plus '+' sign to disable the fast-forward check only on that ref. - -Author ------- -Written by Nick Hengeveld <nickh@reactrix.com> - -Documentation --------------- -Documentation by Nick Hengeveld - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index 57aba42e66..d3013d6a29 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -124,14 +124,6 @@ Thunderbird in particular is known to be problematic. Thunderbird users may wish to visit this web page for more information: http://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email -Author ------- -Derived from isync 1.0.1 by Mike McCormack. - -Documentation --------------- -Documentation by Mike McCormack - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index c2bb81042c..909687fed4 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -85,15 +85,6 @@ new .keep file was successfully created. This is useful to remove a .keep file used as a lock to prevent the race with 'git repack' mentioned above. - -Author ------- -Written by Sergey Vlasov <vsu@altlinux.ru> - -Documentation -------------- -Documentation by Sergey Vlasov - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt index eba3cb4998..2c4c716f33 100644 --- a/Documentation/git-init-db.txt +++ b/Documentation/git-init-db.txt @@ -16,3 +16,7 @@ DESCRIPTION This is a synonym for linkgit:git-init[1]. Please refer to the documentation of that command. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 00d4a124c9..58cd01145a 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -8,9 +8,32 @@ git-init - Create an empty git repository or reinitialize an existing one SYNOPSIS -------- -'git init' [-q | --quiet] [--bare] [--template=<template_directory>] [--shared[=<permissions>]] [directory] +'git init' [-q | --quiet] [--bare] [--template=<template_directory>] + [--separate-git-dir|-L <git dir>] + [--shared[=<permissions>]] [directory] +DESCRIPTION +----------- + +This command creates an empty git repository - basically a `.git` +directory with subdirectories for `objects`, `refs/heads`, +`refs/tags`, and template files. An initial `HEAD` file that +references the HEAD of the master branch is also created. + +If the `$GIT_DIR` environment variable is set then it specifies a path +to use instead of `./.git` for the base of the repository. + +If the object storage directory is specified via the +`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories +are created underneath - otherwise the default `$GIT_DIR/objects` +directory is used. + +Running 'git init' in an existing repository is safe. It will not +overwrite things that are already there. The primary reason for +rerunning 'git init' is to pick up newly added templates (or to move +the repository to another place if --separate-git-dir is given). + OPTIONS ------- @@ -31,6 +54,16 @@ current working directory. Specify the directory from which templates will be used. (See the "TEMPLATE DIRECTORY" section below.) +-L=<git dir>:: +--separate-git-dir=<git dir>:: + +Instead of initializing the repository where it is supposed to be, +place a filesytem-agnostic git symbolic link there, pointing to the +specified git path, and initialize a git repository at the path. The +result is git repository can be separated from working tree. If this +is reinitialization, the repository will be moved to the specified +path. + --shared[=(false|true|umask|group|all|world|everybody|0xxx)]:: Specify that the git repository is to be shared amongst several users. This @@ -74,32 +107,6 @@ line, the command is run inside the directory (possibly after creating it). -- -DESCRIPTION ------------ -This command creates an empty git repository - basically a `.git` directory -with subdirectories for `objects`, `refs/heads`, `refs/tags`, and -template files. -An initial `HEAD` file that references the HEAD of the master branch -is also created. - -If the `$GIT_DIR` environment variable is set then it specifies a path -to use instead of `./.git` for the base of the repository. - -If the object storage directory is specified via the `$GIT_OBJECT_DIRECTORY` -environment variable then the sha1 directories are created underneath - -otherwise the default `$GIT_DIR/objects` directory is used. - -Running 'git init' in an existing repository is safe. It will not overwrite -things that are already there. The primary reason for rerunning 'git init' -is to pick up newly added templates. - -Note that 'git init' is the same as 'git init-db'. The command -was primarily meant to initialize the object database, but over -time it has become responsible for setting up the other aspects -of the repository, such as installing the default hooks and -setting the configuration variables. The old name is retained -for backward compatibility reasons. - TEMPLATE DIRECTORY ------------------ @@ -134,15 +141,6 @@ $ git add . <2> <1> prepare /path/to/my/codebase/.git directory <2> add all existing file to the index - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index 7477ce8fa8..08f85ba046 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -84,14 +84,6 @@ If the configuration variable 'instaweb.browser' is not set, 'web.browser' will be used instead if it is defined. See linkgit:git-web{litdd}browse[1] for more information about this. -Author ------- -Written by Eric Wong <normalperson@yhbt.net> - -Documentation --------------- -Documentation by Eric Wong <normalperson@yhbt.net>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 6d40f0011b..2c84028838 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -25,6 +25,7 @@ OPTIONS -<n>:: Limits the number of commits to show. + Note that this is a commit limiting option, see below. <since>..<until>:: Show only commits between the named two commits. When @@ -72,16 +73,16 @@ produced by --stat etc. to be prefixed with "\-- " to separate them from options or refnames. +include::rev-list-options.txt[] + +include::pretty-formats.txt[] + Common diff options -~~~~~~~~~~~~~~~~~~~ +------------------- :git-log: 1 include::diff-options.txt[] -include::rev-list-options.txt[] - -include::pretty-formats.txt[] - include::diff-generate-patch.txt[] Examples @@ -116,7 +117,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:: @@ -181,14 +182,6 @@ This setting can be disabled by the `--no-standard-notes` option, overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable, and supplemented by the `--show-notes` option. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-lost-found.txt b/Documentation/git-lost-found.txt index 602b8d5d4d..adf7e1c055 100644 --- a/Documentation/git-lost-found.txt +++ b/Documentation/git-lost-found.txt @@ -67,15 +67,6 @@ $ git rev-parse not-lost-anymore 1ef2b196d909eed523d4f3c9bf54b78cdd6843c6 ------------ -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 86abd13451..4b28292811 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -209,15 +209,6 @@ SEE ALSO -------- linkgit:git-read-tree[1], linkgit:gitignore[5] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index abe7bf9ff9..c3df8c0ebe 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git ls-remote' [--heads] [--tags] [-u <exec> | --upload-pack <exec>] - <repository> <refs>... + <repository> [<refs>...] DESCRIPTION ----------- @@ -67,10 +67,6 @@ EXAMPLES c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 7ceca275d047c90c0c7d5afb13ab97efdf51bd6e refs/tags/v0.99.3 -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index 76ed625e7b..16e87fd6dd 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -95,18 +95,6 @@ Object size identified by <object> is given in bytes, and right-justified with minimum width of 7 characters. Object size is given only for blobs (file) entries; for other entries `-` character is used in place of size. - -Author ------- -Written by Petr Baudis <pasky@suse.cz> -Completely rewritten from scratch by Junio C Hamano <gitster@pobox.com>, -another major rewrite by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list -<git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 3ea5aad56c..ed45662cc9 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -80,17 +80,6 @@ This can enabled by default with the configuration option mailinfo.scissors. <patch>:: The patch extracted from e-mail. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <gitster@pobox.com> - - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index 71912a19a4..9b2049d674 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -46,16 +46,6 @@ OPTIONS --keep-cr:: Do not remove `\r` from lines ending with `\r\n`. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> -and Junio C Hamano <gitster@pobox.com> - - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index eedef1bb1a..ba36ec04f4 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -102,14 +102,6 @@ both '1' and '2' are merge-bases of A and B. Neither one is better than the other (both are 'best' merge bases). When the `--all` option is not given, it is unspecified which best one is output. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - See also -------- linkgit:git-rev-list[1], diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index f334d694e0..635c66956e 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -86,17 +86,6 @@ git merge-file -L a -L b -L c tmp/a123 tmp/b234 tmp/c345:: merges tmp/a123 and tmp/c345 with the base tmp/b234, but uses labels `a` and `c` instead of `tmp/a123` and `tmp/c345`. - -Author ------- -Written by Johannes Schindelin <johannes.schindelin@gmx.de> - - -Documentation --------------- -Documentation by Johannes Schindelin and the git-list <git@vger.kernel.org>, -with parts copied from the original documentation of RCS 'merge'. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 921b38f183..6ce54673b0 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -73,15 +73,6 @@ merge once anything has returned an error (i.e., `cat` returned an error for the AA file, because it didn't exist in the original, and thus 'git merge-index' didn't even try to merge the MM thing). -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> -One-shot merge by Petr Baudis <pasky@ucw.cz> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-merge-one-file.txt b/Documentation/git-merge-one-file.txt index a163cfca69..ee059def79 100644 --- a/Documentation/git-merge-one-file.txt +++ b/Documentation/git-merge-one-file.txt @@ -15,15 +15,6 @@ DESCRIPTION This is the standard helper program to use with 'git merge-index' to resolve a merge after the trivial merge done with 'git read-tree -m'. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org>, -Junio C Hamano <gitster@pobox.com> and Petr Baudis <pasky@suse.cz>. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index f869a7f00f..3bfa7b4220 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -23,14 +23,6 @@ merge results outside of the index, and stuff the results back into the index. For this reason, the output from the command omits entries that match the <branch1> tree. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index d43416d299..e2e6aba17e 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -11,8 +11,9 @@ SYNOPSIS [verse] 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>] [-X <strategy-option>] - [--[no-]rerere-autoupdate] [-m <msg>] <commit>... + [--[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. @@ -72,10 +81,27 @@ invocations. 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 - <commit> obviously means you are trying an Octopus. + Specifying more than one commit will create a merge with + more than two parents (affectionately called an Octopus merge). ++ +If no commit is given from the command line, and if `merge.defaultToUpstream` +configuration variable is set, merge the remote tracking branches +that the current branch is configured to use as its upstream. +See also the configuration section of this manual page. PRE-MERGE CHECKS @@ -142,7 +168,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 +239,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 @@ -291,15 +317,6 @@ linkgit:git-diff[1], linkgit:git-ls-files[1], linkgit:git-add[1], linkgit:git-rm[1], linkgit:git-mergetool[1] -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.txt index d8df55362c..63ededec1d 100644 --- a/Documentation/git-mergetool--lib.txt +++ b/Documentation/git-mergetool--lib.txt @@ -41,14 +41,6 @@ run_merge_tool:: '$MERGED', '$LOCAL', '$REMOTE', and '$BASE' must be defined for use by the merge tool. -Author ------- -Written by David Aguilar <davvid@gmail.com> - -Documentation --------------- -Documentation by David Aguilar and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 1f75a848ba..8c79ae8d2a 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -26,8 +26,8 @@ OPTIONS --tool=<tool>:: Use the merge resolution program specified by <tool>. Valid merge tools are: - kdiff3, tkdiff, meld, xxdiff, emerge, vimdiff, gvimdiff, ecmerge, - diffuse, tortoisemerge, opendiff, p4merge and araxis. + araxis, bc3, diffuse, ecmerge, emerge, gvimdiff, kdiff3, + meld, opendiff, p4merge, tkdiff, tortoisemerge, vimdiff and xxdiff. + If a merge resolution program is not specified, 'git mergetool' will use the configuration variable `merge.tool`. If the @@ -82,14 +82,6 @@ Setting the `mergetool.keepBackup` configuration variable to `false` causes `git mergetool` to automatically remove the backup as files are successfully merged. -Author ------- -Written by Theodore Y Ts'o <tytso@mit.edu> - -Documentation --------------- -Documentation by Theodore Y Ts'o. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt index 8bcc11443d..037ab1045d 100644 --- a/Documentation/git-mktag.txt +++ b/Documentation/git-mktag.txt @@ -32,15 +32,6 @@ exists, is separated by a blank line from the header. The message part may contain a signature that git itself doesn't care about, but that can be verified with gpg. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt index 81e3326772..afe21be64d 100644 --- a/Documentation/git-mktree.txt +++ b/Documentation/git-mktree.txt @@ -34,14 +34,6 @@ OPTIONS optional. Note - if the '-z' option is used, lines are terminated with NUL. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt index bdcb58526e..db0e030d69 100644 --- a/Documentation/git-mv.txt +++ b/Documentation/git-mv.txt @@ -39,17 +39,6 @@ OPTIONS --dry-run:: Do nothing; only show what would happen - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> -Rewritten by Ryan Anderson <ryan@michonline.com> -Move functionality added by Josef Weidendorfer <Josef.Weidendorfer@gmx.de> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index 2108237c36..ad1d1468c9 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -70,15 +70,6 @@ Another nice thing you can do is: % git log | git name-rev --stdin ------------ - -Author ------- -Written by Johannes Schindelin <Johannes.Schindelin@gmx.de> - -Documentation --------------- -Documentation by Johannes Schindelin. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 2981d8c5ef..296f314eae 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 65eff66afe..20c8551d6a 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -115,7 +115,7 @@ base-name:: --honor-pack-keep:: This flag causes an object already in a local pack that - has a .keep file to be ignored, even if it it would have + has a .keep file to be ignored, even if it would have otherwise been packed. --incremental:: @@ -190,15 +190,20 @@ self-contained. Use `git index-pack --fix-thin` (see linkgit:git-index-pack[1]) to restore the self-contained property. --delta-base-offset:: - A packed archive can express base object of a delta as - either 20-byte object name or as an offset in the - stream, but older version of git does not understand the + A packed archive can express the base object of a delta as + either a 20-byte object name or as an offset in the + stream, but ancient versions of git don't understand the latter. By default, 'git pack-objects' only uses the former format for better compatibility. This option allows the command to use the latter format for compactness. Depending on the average delta chain length, this option typically shrinks the resulting packfile by 3-5 per-cent. ++ +Note: Porcelain commands such as `git gc` (see linkgit:git-gc[1]), +`git repack` (see linkgit:git-repack[1]) pass this option by default +in modern git when they put objects in your repository into pack files. +So does `git bundle` (see linkgit:git-bundle[1]) when it creates a bundle. --threads=<n>:: Specifies the number of threads to spawn when searching for best @@ -219,15 +224,6 @@ self-contained. Use `git index-pack --fix-thin` With this option, parents that are hidden by grafts are packed nevertheless. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation -------------- -Documentation by Junio C Hamano - SEE ALSO -------- linkgit:git-rev-list[1] diff --git a/Documentation/git-pack-redundant.txt b/Documentation/git-pack-redundant.txt index d0607879db..db9f0f7055 100644 --- a/Documentation/git-pack-redundant.txt +++ b/Documentation/git-pack-redundant.txt @@ -38,14 +38,6 @@ OPTIONS --verbose:: Outputs some statistics to stderr. Has a small performance penalty. -Author ------- -Written by Lukas Sandström <lukass@etek.chalmers.se> - -Documentation --------------- -Documentation by Lukas Sandström <lukass@etek.chalmers.se> - SEE ALSO -------- linkgit:git-pack-objects[1] diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt index 1ee99c208c..54b92534ce 100644 --- a/Documentation/git-pack-refs.txt +++ b/Documentation/git-pack-refs.txt @@ -56,11 +56,6 @@ a repository with many branches of historical interests. The command usually removes loose refs under `$GIT_DIR/refs` hierarchy after packing them. This option tells it not to. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt index 39d9daa7e0..02217f6ba2 100644 --- a/Documentation/git-parse-remote.txt +++ b/Documentation/git-parse-remote.txt @@ -17,14 +17,6 @@ routines to parse files under $GIT_DIR/remotes/ and $GIT_DIR/branches/ and configuration variables that are related to fetching, pulling and pushing. -Author ------- -Written by Junio C Hamano. - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index 4dae1390a5..50e26f43c1 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -29,14 +29,6 @@ OPTIONS <patch>:: The diff to create the ID of. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-peek-remote.txt b/Documentation/git-peek-remote.txt index 87dacd797f..a34d62f0da 100644 --- a/Documentation/git-peek-remote.txt +++ b/Documentation/git-peek-remote.txt @@ -37,14 +37,6 @@ OPTIONS The repository to sync from. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt index abfc6b6ead..9e6202cdff 100644 --- a/Documentation/git-prune-packed.txt +++ b/Documentation/git-prune-packed.txt @@ -36,14 +36,6 @@ OPTIONS --quiet:: Squelch the progress indicator. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Ryan Anderson <ryan@michonline.com> - SEE ALSO -------- linkgit:git-pack-objects[1] diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 4d673a5686..f616a739ef 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -78,14 +78,6 @@ linkgit:git-fsck[1], linkgit:git-gc[1], linkgit:git-reflog[1] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 64009dee31..14609cbd4d 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -26,7 +26,7 @@ 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 +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. @@ -84,6 +84,15 @@ must be given before the options meant for 'git fetch'. --verbose:: Pass --verbose to git-fetch and git-merge. +--[no-]recurse-submodules[=yes|on-demand|no]:: + This option controls if new commits of all populated submodules should + be fetched too (see linkgit:git-config[1] and linkgit:gitmodules[5]). + That might be necessary to get the data needed for merging submodule + commits, a feature git learned in 1.7.3. Notice that the result of a + merge will not be checked out in the submodule, "git submodule update" + has to be called afterwards to bring the work tree up to date with the + merge result. + Options related to merging ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -137,7 +146,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>` @@ -150,9 +159,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 @@ -211,22 +220,19 @@ If you tried a pull which resulted in a complex conflicts and would want to start over, you can recover with 'git reset'. +BUGS +---- +Using --recurse-submodules can only fetch new commits in already checked +out submodules right now. When e.g. upstream added a new submodule in the +just fetched commits of the superproject the submodule itself can not be +fetched, making it impossible to check out that submodule later without +having to do a fetch again. This is expected to be fixed in a future git +version. + SEE ALSO -------- linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> -and Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Jon Loeliger, -David Greaves, -Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index e11660a2e6..88acfcd4cc 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -406,16 +406,6 @@ Commits A and B would no longer belong to a branch with a symbolic name, and so would be unreachable. As such, these commits would be removed by a `git gc` command on the origin repository. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com>, later rewritten in C -by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt index 579e8d2f3b..7f112f3dcd 100644 --- a/Documentation/git-quiltimport.txt +++ b/Documentation/git-quiltimport.txt @@ -49,14 +49,6 @@ The default for the patch directory is patches or the value of the $QUILT_PATCHES environment variable. -Author ------- -Written by Eric Biederman <ebiederm@lnxi.com> - -Documentation --------------- -Documentation by Eric Biederman <ebiederm@lnxi.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 2e78da448f..26fdadc642 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. @@ -412,27 +416,11 @@ turn `core.sparseCheckout` on in order to have sparse checkout support. -BUGS ----- -In order to match a directory with $GIT_DIR/info/sparse-checkout, -trailing slash must be used. The form without trailing slash, while -works with .gitignore, does not work with sparse checkout. - - SEE ALSO -------- linkgit:git-write-tree[1]; linkgit:git-ls-files[1]; linkgit:gitignore[5] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 30e5c0eb14..620d50e71f 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -66,8 +66,9 @@ would be: D---E---F---G master ------------ -The latter form is just a short-hand of `git checkout topic` -followed by `git rebase master`. +*NOTE:* The latter form is just a short-hand of `git checkout topic` +followed by `git rebase master`. When rebase exits `topic` will +remain the checked-out branch. If the upstream branch already contains a change you have made (e.g., because you mailed a patch which was applied upstream), then that commit @@ -279,6 +280,10 @@ which makes little sense. --no-verify:: This option bypasses the pre-rebase hook. See also linkgit:githooks[5]. +--verify:: + Allows the pre-rebase hook to run, which is the default. This option can + be used to override --no-verify. See also linkgit:githooks[5]. + -C<n>:: Ensure at least <n> lines of surrounding context match before and after each change. When fewer lines of surrounding @@ -654,7 +659,6 @@ The ripple effect of a "hard case" recovery is especially bad: 'everyone' downstream from 'topic' will now have to perform a "hard case" recovery too! - BUGS ---- The todo list presented by `--preserve-merges --interactive` does not @@ -677,15 +681,6 @@ by moving the "pick 4" line will result in the following history: 1 --- 2 --- 4 --- 5 ------------ -Authors ------- -Written by Junio C Hamano <gitster@pobox.com> and -Johannes E. Schindelin <johannes.schindelin@gmx.de> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 2790eebaff..f34e0ae1bd 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -151,15 +151,6 @@ SEE ALSO -------- linkgit:git-send-pack[1] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index e50bd9b68d..09057bf90c 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -90,14 +90,6 @@ them. --verbose:: Print extra information on screen. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt index 8fc809f82b..9893376487 100644 --- a/Documentation/git-relink.txt +++ b/Documentation/git-relink.txt @@ -24,14 +24,6 @@ OPTIONS <dir>:: Directories containing a .git/objects/ subdirectory. -Author ------- -Written by Ryan Anderson <ryan@michonline.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt new file mode 100644 index 0000000000..68263a6a53 --- /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 '<command>' to connect +to a remote git server. + +Data written to stdin of the specified '<command>' is assumed +to be sent to a git:// server, git-upload-pack, git-receive-pack +or git-upload-archive (depending on situation), and data read +from stdout of <command> is assumed to be received from +the same service. + +Command and arguments are separated by an 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 the first characters in an argument):: + This argument will not be passed to '<command>'. Instead, it + will cause the helper to start by sending git:// service requests to + the remote side with the service field set to an appropriate value and + the repository field set to rest of the argument. Default is not to send + such a 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 '<command>'. Instead it sets + the vhost field in the 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 0000000000..4aecd4d187 --- /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 a 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 a 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 a 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 providing +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-helpers.txt b/Documentation/git-remote-helpers.txt index 3a23477ce7..87cd11f2c4 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -201,12 +201,12 @@ REF LIST ATTRIBUTES OPTIONS ------- -'option verbosity' <N>:: +'option verbosity' <n>:: Changes the verbosity of messages displayed by the helper. - A value of 0 for N means that processes operate + A value of 0 for <n> means that processes operate quietly, and the helper produces only error output. 1 is the default level of verbosity, and higher values - of N correspond to the number of -v flags passed on the + of <n> correspond to the number of -v flags passed on the command line. 'option progress' \{'true'|'false'\}:: @@ -239,10 +239,6 @@ SEE ALSO -------- linkgit:git-remote[1] -Documentation -------------- -Documentation by Daniel Barkalow and Ilari Liusvaara - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 0d28febe1b..528f34a131 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git remote' [-v | --verbose] -'git remote add' [-t <branch>] [-m <master>] [-f] [--tags|--no-tags] [--mirror] <name> <url> +'git remote add' [-t <branch>] [-m <master>] [-f] [--tags|--no-tags] [--mirror=<fetch|push>] <name> <url> 'git remote rename' <old> <new> 'git remote rm' <name> 'git remote set-head' <name> (-a | -d | <branch>) @@ -67,15 +67,18 @@ multiple branches without grabbing all branches. With `-m <master>` option, `$GIT_DIR/remotes/<name>/HEAD` is set up to point at remote's `<master>` branch. See also the set-head command. + -In mirror mode, enabled with `\--mirror`, the refs will not be stored -in the 'refs/remotes/' namespace, but in 'refs/heads/'. This option -only makes sense in bare repositories. If a remote uses mirror -mode, furthermore, `git push` will always behave as if `\--mirror` -was passed. +When a fetch mirror is created with `\--mirror=fetch`, the refs will not +be stored in the 'refs/remotes/' namespace, but rather everything in +'refs/' on the remote will be directly mirrored into 'refs/' in the +local repository. This option only makes sense in bare repositories, +because a fetch would overwrite any local commits. ++ +When a push mirror is created with `\--mirror=push`, then `git push` +will always behave as if `\--mirror` 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 +87,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 +149,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>". @@ -214,16 +217,6 @@ linkgit:git-fetch[1] linkgit:git-branch[1] linkgit:git-config[1] -Author ------- -Written by Junio Hamano - - -Documentation --------------- -Documentation by J. Bruce Fields and the git-list <git@vger.kernel.org>. - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 27f7865b06..0decee240b 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -123,15 +123,6 @@ need to set the configuration variable `repack.UseDeltaBaseOffset` to is unaffected by this option as the conversion is performed on the fly as needed in that case. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Ryan Anderson <ryan@michonline.com> - SEE ALSO -------- linkgit:git-pack-objects[1] diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index fde2092582..17df525275 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -80,17 +80,6 @@ linkgit:git-tag[1] linkgit:git-branch[1] linkgit:git[1] -Author ------- -Written by Christian Couder <chriscool@tuxfamily.org> and Junio C -Hamano <gitster@pobox.com>, based on 'git tag' by Kristian Hogsberg -<krh@redhat.com> and Carlos Rica <jasampler@gmail.com>. - -Documentation --------------- -Documentation by Christian Couder <chriscool@tuxfamily.org> and the -git-list <git@vger.kernel.org>, based on 'git tag' documentation. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-repo-config.txt b/Documentation/git-repo-config.txt index e5bdb5533e..a0d1fa6594 100644 --- a/Documentation/git-repo-config.txt +++ b/Documentation/git-repo-config.txt @@ -16,3 +16,7 @@ DESCRIPTION This is a synonym for linkgit:git-config[1]. Please refer to the documentation of that command. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-request-pull.txt b/Documentation/git-request-pull.txt index 400f61f6e2..3521d8e3c8 100644 --- a/Documentation/git-request-pull.txt +++ b/Documentation/git-request-pull.txt @@ -29,14 +29,6 @@ OPTIONS <end>:: Commit to end at; defaults to HEAD. -Author ------- -Written by Ryan Anderson <ryan@michonline.com> and Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt index db99d4786e..52db1d80cf 100644 --- a/Documentation/git-rerere.txt +++ b/Documentation/git-rerere.txt @@ -7,7 +7,7 @@ git-rerere - Reuse recorded resolution of conflicted merges SYNOPSIS -------- -'git rerere' ['clear'|'forget' [<pathspec>]|'diff'|'status'|'gc'] +'git rerere' ['clear'|'forget' <pathspec>|'diff'|'status'|'gc'] DESCRIPTION ----------- @@ -43,7 +43,7 @@ will automatically invoke this command. 'forget' <pathspec>:: This resets the conflict resolutions which rerere has recorded for the current -conflict in <pathspec>. The <pathspec> is optional. +conflict in <pathspec>. 'diff':: @@ -205,11 +205,6 @@ would conflict the same way as the test merge you resolved earlier. 'git rerere' will be run by 'git rebase' to help you resolve this conflict. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index fd72976371..8481f9db74 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -76,15 +76,10 @@ In other words, --merge does something like a 'git read-tree -u -m <commit>', but carries forward unmerged index entries. --keep:: - 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). + Resets index entries and updates files in the working tree that are + different between <commit> and HEAD. 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, @@ -402,15 +397,6 @@ entries: X means any state and U means an unmerged index. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 8e1e32908c..415f4f0b30 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -16,6 +16,10 @@ SYNOPSIS [ \--sparse ] [ \--merges ] [ \--no-merges ] + [ \--min-parents=<number> ] + [ \--no-min-parents ] + [ \--max-parents=<number> ] + [ \--no-max-parents ] [ \--first-parent ] [ \--remove-empty ] [ \--full-history ] @@ -31,6 +35,9 @@ SYNOPSIS [ \--parents ] [ \--timestamp ] [ \--left-right ] + [ \--left-only ] + [ \--right-only ] + [ \--cherry-mark ] [ \--cherry-pick ] [ \--encoding[=<encoding>] ] [ \--(author|committer|grep)=<pattern> ] @@ -105,16 +112,6 @@ include::rev-list-options.txt[] include::pretty-formats.txt[] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano, Jonas Fonseca -and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 4a27643c1e..02c44c999f 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -136,7 +136,12 @@ appending `/{asterisk}`. directory (typically a sequence of "../", or an empty string). --git-dir:: - Show `$GIT_DIR` if defined else show the path to the .git directory. + Show `$GIT_DIR` if defined. Otherwise show the path to + the .git directory, relative to the current directory. ++ +If `$GIT_DIR` is not defined and the current directory +is not detected to lie in a git repository or work tree +print a message to stderr and exit with nonzero status. --is-inside-git-dir:: When the current working directory is below the repository @@ -303,16 +308,6 @@ $ git rev-parse --default master --verify $REV + but if $REV is empty, the commit object name from master will be printed. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> . -Junio C Hamano <gitster@pobox.com> and Pierre Habouzit <madcoder@debian.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt index 752fc88e76..ac10cfbb14 100644 --- a/Documentation/git-revert.txt +++ b/Documentation/git-revert.txt @@ -80,6 +80,16 @@ effect to your index in a row. --signoff:: Add Signed-off-by line at the end of the commit message. +--strategy=<strategy>:: + Use the given merge strategy. Should only be used once. + See the MERGE STRATEGIES section in linkgit:git-merge[1] + for details. + +-X<option>:: +--strategy-option=<option>:: + Pass the merge strategy-specific option through to the + merge strategy. See linkgit:git-merge[1] for details. + EXAMPLES -------- git revert HEAD~3:: @@ -95,14 +105,6 @@ git revert -n master{tilde}5..master{tilde}2:: changes. The revert only modifies the working tree and the index. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - SEE ALSO -------- linkgit:git-cherry-pick[1] diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 0adbe8b1f8..8c0554f971 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -153,14 +153,6 @@ SEE ALSO -------- linkgit:git-add[1] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index adbca12b1e..ee14f74fd3 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. @@ -318,7 +348,6 @@ sendemail.confirm:: one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm' in the previous section for the meaning of these values. - Use gmail as the smtp server ---------------------------- @@ -333,20 +362,6 @@ Add the following section to the config file: Note: the following perl modules are required Net::SMTP::SSL, MIME::Base64 and Authen::SASL - -Author ------- -Written by Ryan Anderson <ryan@michonline.com> - -git-send-email is originally based upon -send_lots_of_email.pl by Greg Kroah-Hartman. - - -Documentation --------------- -Documentation by Ryan Anderson - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index deaa7d9654..17f8f55526 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -114,15 +114,6 @@ With '--force', the fast-forward check is disabled for all refs. Optionally, a <ref> parameter can be prefixed with a plus '+' sign to disable the fast-forward check only on that ref. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt index 3da241304b..053df505bc 100644 --- a/Documentation/git-sh-setup.txt +++ b/Documentation/git-sh-setup.txt @@ -66,15 +66,6 @@ get_author_ident_from_commit:: outputs code for use with eval to set the GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL and GIT_AUTHOR_DATE variables for a given commit. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt index 0f3ad811cf..d7d4b92894 100644 --- a/Documentation/git-shell.txt +++ b/Documentation/git-shell.txt @@ -3,32 +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'). - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Petr Baudis and the git-list <git@vger.kernel.org>. + +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. GIT --- diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 5cc3baf48d..ff3755b4c7 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -68,15 +68,6 @@ spelled differently. include::mailmap.txt[] - -Author ------- -Written by Jeff Garzik <jgarzik@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 3b0c88271a..ee4559b6f2 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -200,17 +200,6 @@ shows 10 reflog entries going back from the tip as of 1 hour ago. Without `--list`, the output also shows how these tips are topologically related with each other. - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - - -Documentation --------------- -Documentation by Junio C Hamano. - - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt index 8382fbe0ec..c4d99f1028 100644 --- a/Documentation/git-show-index.txt +++ b/Documentation/git-show-index.txt @@ -20,15 +20,6 @@ The information it outputs is subset of what you can get from 'git verify-pack -v'; this command only shows the packfile offset and SHA1 of each object. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index be0ec189af..3c45895299 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -177,11 +177,6 @@ linkgit:git-ls-remote[1], linkgit:git-update-ref[1], linkgit:gitrepository-layout[5] -AUTHORS -------- -Written by Linus Torvalds <torvalds@osdl.org>. -Man page by Jonas Fonseca <fonseca@diku.dk>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt index f0a8a1aff3..7f075e84f5 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -72,17 +72,6 @@ Discussion include::i18n.txt[] -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <gitster@pobox.com>. Significantly enhanced by -Johannes Schindelin <Johannes.Schindelin@gmx.de>. - - -Documentation -------------- -Documentation by David Greaves, Petr Baudis and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt index 7f251a5865..ba3fe0d7f5 100644 --- a/Documentation/git-stage.txt +++ b/Documentation/git-stage.txt @@ -17,3 +17,7 @@ DESCRIPTION This is a synonym for linkgit:git-add[1]. Please refer to the documentation of that command. + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 8728f7a514..79abc38e50 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -257,10 +257,6 @@ linkgit:git-commit[1], linkgit:git-reflog[1], linkgit:git-reset[1] -AUTHOR ------- -Written by Nanako Shiraishi <nanako3@bluebottle.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index dae190a5f2..00b699fef7 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -38,20 +38,20 @@ OPTIONS -u[<mode>]:: --untracked-files[=<mode>]:: - Show untracked files (Default: 'all'). + Show untracked files. + -The mode parameter is optional, and is used to specify -the handling of untracked files. The possible options are: +The mode parameter is optional (defaults to 'all'), and is used to +specify the handling of untracked files; when -u is not used, the +default is 'normal', i.e. show untracked files and directories. ++ +The possible options are: + --- - 'no' - Show no untracked files - 'normal' - Shows untracked files and directories - 'all' - Also shows individual files in untracked directories. --- + -See linkgit:git-config[1] for configuration variable -used to change the default for when the option is not -specified. +The default can be changed using the status.showUntrackedFiles +configuration variable documented in linkgit:git-config[1]. --ignore-submodules[=<when>]:: Ignore changes to submodules when looking for changes. <when> can be @@ -174,14 +174,6 @@ SEE ALSO -------- linkgit:gitignore[5] -Author ------- -Written by Junio C Hamano <gitster@pobox.com>. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt index 7508c0e42d..10509cc450 100644 --- a/Documentation/git-stripspace.txt +++ b/Documentation/git-stripspace.txt @@ -23,14 +23,6 @@ OPTIONS <stream>:: Byte stream to act on. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 1ed331c599..1a16ff6044 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -101,9 +101,10 @@ status:: currently checked out commit for each submodule, along with the submodule path and the output of 'git describe' for the SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not - initialized and `+` if the currently checked out submodule commit + initialized, `+` if the currently checked out submodule commit does not match the SHA-1 found in the index of the containing - repository. This command is the default command for 'git submodule'. + repository and `U` if the submodule has merge conflicts. + This command is the default command for 'git submodule'. + If '--recursive' is specified, this command will recurse into nested submodules, and show their status as well. @@ -257,11 +258,6 @@ This file should be formatted in the same way as `$GIT_DIR/config`. The key to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] for details. - -AUTHOR ------- -Written by Lars Hjemli <hjemli@gmail.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 139d314ba5..30a67486d2 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -66,7 +66,7 @@ COMMANDS Set the 'rewriteRoot' option in the [svn-remote] config. --rewrite-uuid=<UUID>;; Set the 'rewriteUUID' option in the [svn-remote] config. ---username=<USER>;; +--username=<user>;; For transports that SVN handles authentication for (http, https, and plain svn), specify the username. For other transports (eg svn+ssh://), you must include the username in @@ -217,6 +217,13 @@ config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options) Using this option for any other purpose (don't ask) is very strongly discouraged. +--mergeinfo=<mergeinfo>;; + Add the given merge information during the dcommit + (e.g. `--mergeinfo="/branches/foo:1-10"`). All svn server versions can + store this information (as a property), and svn clients starting from + version 1.5 can make use of it. 'git svn' currently does not use it + and does not set it automatically. + 'branch':: Create a branch in the SVN repository. @@ -443,8 +450,8 @@ OPTIONS Only used with the 'init' command. These are passed directly to 'git init'. --r <ARG>:: ---revision <ARG>:: +-r <arg>:: +--revision <arg>:: Used with the 'fetch' command. + This allows revision ranges for partial/cauterized history @@ -613,7 +620,7 @@ old references to SVN revision numbers in existing documentation, bug reports and archives. If you plan to eventually migrate from SVN to git and are certain about dropping SVN history, consider linkgit:git-filter-branch[1] instead. filter-branch also allows -reformating of metadata for ease-of-reading and rewriting authorship +reformatting of metadata for ease-of-reading and rewriting authorship info for non-"svn.authorsFile" users. svn.useSvmProps:: @@ -648,6 +655,16 @@ svn-remote.<name>.rewriteUUID:: where the original UUID is not available via either useSvmProps or useSvnsyncProps. +svn-remote.<name>.pushurl:: + + Similar to git's 'remote.<name>.pushurl', this key is designed + to be used in cases where 'url' points to an SVN repository + via a read-only transport, to provide an alternate read/write + transport. It is assumed that both keys point to the same + repository. Unlike 'commiturl', 'pushurl' is a base path. If + either 'commiturl' or 'pushurl' could be used, 'commiturl' + takes precedence. + svn.brokenSymlinkWorkaround:: This disables potentially expensive checks to workaround broken symlinks checked into SVN by broken clients. Set this @@ -729,8 +746,11 @@ have each person clone that repository with 'git clone': cd project git init git remote add origin server:/pub/project - git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*' + git config --replace-all remote.origin.fetch '+refs/remotes/*:refs/remotes/*' git fetch +# Prevent fetch/pull from remote git server in the future, +# we only want to use git svn for future updates + git config --remove-section remote.origin # Create a local branch from one of the branches just fetched git checkout -b master FETCH_HEAD # Initialize 'git svn' locally (be sure to use the same URL and -T/-b/-t options as were used on server) @@ -875,10 +895,6 @@ SEE ALSO -------- linkgit:git-rebase[1] -Author ------- -Written by Eric Wong <normalperson@yhbt.net>. - -Documentation -------------- -Written by Eric Wong <normalperson@yhbt.net>. +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 33a1536294..d7795ed657 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -53,10 +53,6 @@ and symbolic refs are used by default. symbolic ref were printed correctly, with status 1 if the requested name is not a symbolic ref, or 128 if another error occurs. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 31c78a81e0..d82f62120a 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -18,21 +18,22 @@ SYNOPSIS DESCRIPTION ----------- -Adds a tag reference in `.git/refs/tags/`. +Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given +to delete, list or verify tags. -Unless `-f` is given, the tag must not yet exist in +Unless `-f` is given, the tag to be created must not yet exist in the `.git/refs/tags/` directory. If one of `-a`, `-s`, or `-u <key-id>` is passed, the command -creates a 'tag' object, and requires the tag message. Unless +creates a 'tag' object, and requires a tag message. Unless `-m <msg>` or `-F <file>` is given, an editor is started for the user to type in the tag message. If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied. -Otherwise just the SHA1 object name of the commit object is -written (i.e. a lightweight tag). +Otherwise just a tag reference for the SHA1 object name of the commit object is +created (i.e. a lightweight tag). A GnuPG signed tag object will be created when `-s` or `-u <key-id>` is used. When `-u <key-id>` is not used, the @@ -164,20 +165,19 @@ You can test which tag you have by doing which should return 0123456789abcdef.. if you have the new version. -Sorry for inconvenience. +Sorry for the inconvenience. ------------ Does this seem a bit complicated? It *should* be. There is no -way that it would be correct to just "fix" it behind peoples -backs. People need to know that their tags might have been -changed. +way that it would be correct to just "fix" it automatically. +People need to know that their tags might have been changed. 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. @@ -188,9 +188,10 @@ the toplevel but not limited to them. Mere mortals when pulling from each other do not necessarily want to automatically get private anchor point tags from the other person. -You would notice "please pull" messages on the mailing list says -repo URL and branch name alone. This is designed to be easily -cut&pasted to a 'git fetch' command line: +Often, "please pull" messages on the mailing list just provide +two pieces of information: a repo URL and a branch name; this +is designed to be easily cut&pasted at the end of a 'git fetch' +command line: ------------ Linus, please pull from @@ -206,14 +207,14 @@ becomes: $ git pull git://git..../proj.git master ------------ -In such a case, you do not want to automatically follow other's -tags. +In such a case, you do not want to automatically follow the other +person's tags. -One important aspect of git is it is distributed, and being -distributed largely means there is no inherent "upstream" or +One important aspect of git is its distributed nature, which +largely means there is no inherent "upstream" or "downstream" in the system. On the face of it, the above example might seem to indicate that the tag namespace is owned -by upper echelon of people and tags only flow downwards, but +by the upper echelon of people and that tags only flow downwards, but that is not the case. It only shows that the usage pattern determines who are interested in whose tags. @@ -231,8 +232,8 @@ 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 +they are most likely tracking each other's progress by +having remote-tracking branches. Again, the heuristic to automatically follow such tags is a good thing. @@ -241,35 +242,26 @@ On Backdating Tags If you have imported some changes from another VCS and would like to add tags for major releases of your work, it is useful to be able -to specify the date to embed inside of the tag object. The data in +to specify the date to embed inside of the tag object; such data in the tag object affects, for example, the ordering of tags in the gitweb interface. To set the date used in future tag objects, set the environment -variable GIT_COMMITTER_DATE to one or more of the date and time. The -date and time can be specified in a number of ways; the most common -is "YYYY-MM-DD HH:MM". +variable GIT_COMMITTER_DATE (see the later discussion of possible +values; the most common form is "YYYY-MM-DD HH:MM"). -An example follows. +For example: ------------ $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1 ------------ +include::date-formats.txt[] SEE ALSO -------- linkgit:git-check-ref-format[1]. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org>, -Junio C Hamano <gitster@pobox.com> and Chris Wright <chrisw@osdl.org>. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt index 3c786bd283..5f15754257 100644 --- a/Documentation/git-tar-tree.txt +++ b/Documentation/git-tar-tree.txt @@ -76,14 +76,6 @@ git tar-tree HEAD:Documentation/ git-docs > git-1.4.0-docs.tar:: Put everything in the current head's Documentation/ directory into 'git-1.4.0-docs.tar', with the prefix 'git-docs/'. -Author ------- -Written by Rene Scharfe. - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-unpack-file.txt b/Documentation/git-unpack-file.txt index 995db9fead..c49d727f74 100644 --- a/Documentation/git-unpack-file.txt +++ b/Documentation/git-unpack-file.txt @@ -22,14 +22,6 @@ OPTIONS <blob>:: Must be a blob id -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index 36d1038056..dd7799095b 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -43,15 +43,6 @@ OPTIONS --strict:: Don't write objects with broken content or links. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation -------------- -Documentation by Junio C Hamano - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 1ca56c85aa..d3931294d1 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -365,15 +365,6 @@ SEE ALSO linkgit:git-config[1], linkgit:git-add[1] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 9639f705af..e25a65a80f 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -84,10 +84,6 @@ An update will fail (without changing <ref>) if the current user is unable to create a new log file, append to the existing log file or does not have committer information available. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-update-server-info.txt b/Documentation/git-update-server-info.txt index 035cc3018f..775024da3e 100644 --- a/Documentation/git-update-server-info.txt +++ b/Documentation/git-update-server-info.txt @@ -38,15 +38,6 @@ what they are for: * info/refs - -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-upload-archive.txt b/Documentation/git-upload-archive.txt index f5f2b3908b..acbf634f85 100644 --- a/Documentation/git-upload-archive.txt +++ b/Documentation/git-upload-archive.txt @@ -24,14 +24,6 @@ OPTIONS <directory>:: The repository to get a tar archive from. -Author ------- -Written by Franck Bui-Huu. - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 71ca4ef442..4c0ca9ded2 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -33,14 +33,6 @@ OPTIONS <directory>:: The repository to sync from. -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by Junio C Hamano. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index 458f3e2755..6498f7cb69 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -65,14 +65,6 @@ linkgit:git-commit-tree[1] linkgit:git-tag[1] linkgit:git-config[1] -Author ------- -Written by Eric Biederman <ebiederm@xmission.com> - -Documentation --------------- -Documentation by Eric Biederman and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-verify-pack.txt b/Documentation/git-verify-pack.txt index 916a38aa99..7c2428d569 100644 --- a/Documentation/git-verify-pack.txt +++ b/Documentation/git-verify-pack.txt @@ -8,7 +8,7 @@ git-verify-pack - Validate packed git archive files SYNOPSIS -------- -'git verify-pack' [-v|--verbose] [--] <pack>.idx ... +'git verify-pack' [-v|--verbose] [-s|--stat-only] [--] <pack>.idx ... DESCRIPTION @@ -47,14 +47,6 @@ for objects that are not deltified in the pack, and for objects that are deltified. -Author ------- -Written by Junio C Hamano <gitster@pobox.com> - -Documentation --------------- -Documentation by Junio C Hamano - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-verify-tag.txt b/Documentation/git-verify-tag.txt index dada21242c..8c9a71865b 100644 --- a/Documentation/git-verify-tag.txt +++ b/Documentation/git-verify-tag.txt @@ -15,17 +15,13 @@ 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. -Author ------- -Written by Jan Harkes <jaharkes@cs.cmu.edu> and Eric W. Biederman <ebiederm@xmission.com> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index 51e8e0af1e..69d92fa00e 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -20,8 +20,14 @@ The following browsers (or commands) are currently supported: * firefox (this is the default under X Window when not using KDE) * iceweasel +* seamonkey +* iceape +* chromium (also supported as chromium-browser) +* google-chrome (also supported as chrome) * konqueror (this is the default under KDE, see 'Note about konqueror' below) +* opera * w3m (this is the default outside graphical environments) +* elinks * links * lynx * dillo @@ -110,16 +116,6 @@ $ git config --global web.browser firefox as they are probably more user specific than repository specific. See linkgit:git-config[1] for more information about this. -Author ------- -Written by Christian Couder <chriscool@tuxfamily.org> and the git-list -<git@vger.kernel.org>, based on 'git mergetool' by Theodore Y. Ts'o. - -Documentation -------------- -Documentation by Christian Couder <chriscool@tuxfamily.org> and the -git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt index ea753cdafc..31f3663ae7 100644 --- a/Documentation/git-whatchanged.txt +++ b/Documentation/git-whatchanged.txt @@ -63,17 +63,6 @@ git whatchanged --since="2 weeks ago" \-- gitk:: The "--" is necessary to avoid confusion with the *branch* named 'gitk' - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <gitster@pobox.com> - - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt index bfceacacb3..e8c94c1352 100644 --- a/Documentation/git-write-tree.txt +++ b/Documentation/git-write-tree.txt @@ -36,15 +36,6 @@ OPTIONS `<prefix>`. This can be used to write the tree object for a subproject that is in the named subdirectory. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> - -Documentation --------------- -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git.txt b/Documentation/git.txt index 0c897df6a7..78420b133a 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -44,31 +44,56 @@ 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.2/git.html[documentation for release 1.7.3.2] +* link:v1.7.5.1/git.html[documentation for release 1.7.5.1] * release notes for + link:RelNotes/1.7.5.1.txt[1.7.5.1], + link:RelNotes/1.7.5.txt[1.7.5]. + +* link:v1.7.4.5/git.html[documentation for release 1.7.4.5] + +* release notes for + link:RelNotes/1.7.4.5.txt[1.7.4.5], + link:RelNotes/1.7.4.4.txt[1.7.4.4], + link:RelNotes/1.7.4.3.txt[1.7.4.3], + link:RelNotes/1.7.4.2.txt[1.7.4.2], + link:RelNotes/1.7.4.1.txt[1.7.4.1], + link:RelNotes/1.7.4.txt[1.7.4]. + +* link:v1.7.3.5/git.html[documentation for release 1.7.3.5] + +* release notes for + link:RelNotes/1.7.3.5.txt[1.7.3.5], + link:RelNotes/1.7.3.4.txt[1.7.3.4], + 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.5/git.html[documentation for release 1.7.2.5] * release notes for + link:RelNotes/1.7.2.5.txt[1.7.2.5], + 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.4/git.html[documentation for release 1.7.1.4] * release notes for + link:RelNotes/1.7.1.4.txt[1.7.1.4], + 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.9/git.html[documentation for release 1.7.0.9] * release notes for + link:RelNotes/1.7.0.9.txt[1.7.0.9], + 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], @@ -78,16 +103,18 @@ Documentation for older releases are available here: link:RelNotes/1.7.0.1.txt[1.7.0.1], link:RelNotes/1.7.0.txt[1.7.0]. -* link:v1.6.6.2/git.html[documentation for release 1.6.6.2] +* link:v1.6.6.3/git.html[documentation for release 1.6.6.3] * release notes for + link:RelNotes/1.6.6.3.txt[1.6.6.3], link:RelNotes/1.6.6.2.txt[1.6.6.2], link:RelNotes/1.6.6.1.txt[1.6.6.1], link:RelNotes/1.6.6.txt[1.6.6]. -* link:v1.6.5.8/git.html[documentation for release 1.6.5.8] +* link:v1.6.5.9/git.html[documentation for release 1.6.5.9] * release notes for + link:RelNotes/1.6.5.9.txt[1.6.5.9], link:RelNotes/1.6.5.8.txt[1.6.5.8], link:RelNotes/1.6.5.7.txt[1.6.5.7], link:RelNotes/1.6.5.6.txt[1.6.5.6], @@ -98,9 +125,10 @@ Documentation for older releases are available here: link:RelNotes/1.6.5.1.txt[1.6.5.1], link:RelNotes/1.6.5.txt[1.6.5]. -* link:v1.6.4.4/git.html[documentation for release 1.6.4.4] +* link:v1.6.4.5/git.html[documentation for release 1.6.4.5] * release notes for + link:RelNotes/1.6.4.5.txt[1.6.4.5], link:RelNotes/1.6.4.4.txt[1.6.4.4], link:RelNotes/1.6.4.3.txt[1.6.4.3], link:RelNotes/1.6.4.2.txt[1.6.4.2], @@ -279,17 +307,12 @@ help ...`. path or relative path to current working directory. --work-tree=<path>:: - Set the path to the working tree. The value will not be - used in combination with repositories found automatically in - a .git directory (i.e. $GIT_DIR is not set). + Set the path to the working tree. It can be an absolute path + or a path relative to the current working directory. This can also be controlled by setting the GIT_WORK_TREE environment variable and the core.worktree configuration - variable. It can be an absolute path or relative path to - the directory specified by --git-dir or GIT_DIR. - Note: If --git-dir or GIT_DIR are specified but none of - --work-tree, GIT_WORK_TREE and core.worktree is specified, - the current working directory is regarded as the top directory - of your working tree. + variable (see core.worktree in linkgit:git-config[1] for a + more detailed discussion). --bare:: Treat the repository as a bare repository. If GIT_DIR @@ -606,7 +629,6 @@ where: contents of <old|new>, <old|new>-hex:: are the 40-hexdigit SHA1 hashes, <old|new>-mode:: are the octal representation of the file modes. - + The file parameters can point at the user's working file (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file` @@ -732,16 +754,12 @@ unmerged version of a file when a merge is in progress. Authors ------- -* git's founding father is Linus Torvalds <torvalds@osdl.org>. -* The current git nurse is Junio C Hamano <gitster@pobox.com>. -* The git potty was written by Andreas Ericsson <ae@op5.se>. -* General upbringing is handled by the git-list <git@vger.kernel.org>. - -Documentation --------------- -The documentation for git suite was started by David Greaves -<david@dgreaves.com>, and later enhanced greatly by the -contributors on the git-list <git@vger.kernel.org>. +Git was started by Linus Torvalds, and is currently maintained by Junio +C Hamano. Numerous contributions have come from the git mailing list +<git@vger.kernel.org>. For a more complete list of contributors, see +http://git-scm.com/about. If you have a clone of git.git itself, the +output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you +the authors for specific parts of the project. Reporting Bugs -------------- diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 4641d49f76..15aebc6062 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 @@ -328,6 +335,16 @@ input that is already correctly indented. In this case, the lack of a smudge filter means that the clean filter _must_ accept its own output without modifying it. +Sequence "%f" on the filter command line is replaced with the name of +the file the filter is working on. A filter might use this in keyword +substitution. For example: + +------------------------ +[filter "p4"] + clean = git-p4-filter --clean %f + smudge = git-p4-filter --smudge %f +------------------------ + Interaction between checkin/checkout attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -487,6 +504,8 @@ patterns are available: - `pascal` suitable for source code in the Pascal/Delphi language. +- `perl` suitable for source code in the Perl language. + - `php` suitable for source code in the PHP language. - `python` suitable for source code in the Python language. @@ -613,7 +632,7 @@ Performing a three-way merge `merge` ^^^^^^^ -The attribute `merge` affects how three versions of a file is +The attribute `merge` affects how three versions of a file are merged when a file-level merge is necessary during `git merge`, and other commands such as `git revert` and `git cherry-pick`. @@ -627,15 +646,15 @@ Unset:: Take the version from the current branch as the tentative merge result, and declare that the merge has - conflicts. This is suitable for binary files that does + conflicts. This is suitable for binary files that do not have a well-defined merge semantics. Unspecified:: By default, this uses the same built-in 3-way merge - driver as is the case the `merge` attribute is set. - However, `merge.default` configuration variable can name - different merge driver to be used for paths to which the + driver as is the case when the `merge` attribute is set. + However, the `merge.default` configuration variable can name + different merge driver to be used with paths for which the `merge` attribute is unspecified. String:: @@ -749,6 +768,8 @@ control per path. Set:: Notice all types of potential whitespace errors known to git. + The tab width is taken from the value of the `core.whitespace` + configuration variable. Unset:: @@ -756,13 +777,13 @@ Unset:: Unspecified:: - Use the value of `core.whitespace` configuration variable to + Use the value of the `core.whitespace` configuration variable to decide what to notice as error. String:: Specify a comma separate list of common whitespace problems to - notice in the same format as `core.whitespace` configuration + notice in the same format as the `core.whitespace` configuration variable. diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 6928724a05..f734f97b8e 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -169,10 +169,6 @@ See also http://marc.info/?l=git&m=116563135620359 and http://marc.info/?l=git&m=119150393620273 for further information. -Documentation -------------- -Documentation by Pierre Habouzit and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 5d91a7e5b3..6af29a4603 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 8416f3445a..2e7328b830 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -156,11 +156,6 @@ 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, -Frank Lichtenheld, and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index e21bac4f3f..e10ac58cae 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -113,15 +113,6 @@ SEE ALSO A minimal repository browser and git tool output highlighter written in C using Ncurses. -Author ------- -Written by Paul Mackerras <paulus@samba.org>. - -Documentation --------------- -Documentation by Junio C Hamano, Jonas Fonseca, and the git-list -<git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index bcffd95ada..4040941e55 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -44,6 +44,14 @@ submodule.<name>.update:: This config option is overridden if 'git submodule update' is given the '--merge' or '--rebase' options. +submodule.<name>.fetchRecurseSubmodules:: + This option can be used to control recursive fetching of this + submodule. If this option is also present in the submodules entry in + .git/config of the superproject, the setting there will override the + one found in .gitmodules. + Both settings can be overridden on the command line by using the + "--[no-]recurse-submodules" option to "git fetch" and "git pull". + submodule.<name>.ignore:: Defines under what circumstances "git status" and the diff family show a submodule as modified. When set to "all", it will never be considered @@ -82,10 +90,6 @@ SEE ALSO -------- linkgit:git-submodule[1] linkgit:git-config[1] -DOCUMENTATION -------------- -Documentation by Lars Hjemli <hjemli@gmail.com> - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/gittutorial-2.txt b/Documentation/gittutorial-2.txt index ecab0c09d0..7fe5848d1f 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 1c1606696e..0982f74ef6 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 1f029f8aa0..33716a31d0 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`. @@ -273,6 +273,29 @@ This commit is referred to as a "merge commit", or sometimes just a <<def_pack,pack>>, to assist in efficiently accessing the contents of a pack. +[[def_pathspec]]pathspec:: + Pattern used to specify paths. ++ +Pathspecs are used on the command line of "git ls-files", "git +ls-tree", "git grep", "git checkout", and many other commands to +limit the scope of operations to some subset of the tree or +worktree. See the documentation of each command for whether +paths are relative to the current directory or toplevel. The +pathspec syntax is as follows: + +* any path matches itself +* the pathspec up to the last slash represents a + directory prefix. The scope of that pathspec is + limited to that subtree. +* the rest of the pathspec is a pattern for the remainder + of the pathname. Paths relative to the directory + prefix will be matched against that pattern using fnmatch(3); + in particular, '*' and '?' _can_ match directory separators. ++ +For example, Documentation/*.jpg will match all .jpg files +in the Documentation subtree, +including Documentation/chapter_1/figure_1.jpg. + [[def_parent]]parent:: A <<def_commit_object,commit object>> contains a (possibly empty) list of the logical predecessor(s) in the line of development, i.e. its @@ -349,6 +372,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 +449,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/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt index 0953a50b69..2933056120 100644 --- a/Documentation/howto/using-merge-subtree.txt +++ b/Documentation/howto/using-merge-subtree.txt @@ -71,5 +71,5 @@ Additional tips relevant parts of your tree. - Please note that if the other project merges from you, then it will - connects its history to yours, which can be something they don't want + connect its history to yours, which can be something they don't want to. diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index b72f533970..8920258baa 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -6,9 +6,21 @@ merge.conflictstyle:: a `>>>>>>>` marker. An alternate style, "diff3", adds a `|||||||` marker and the original text before the `=======` marker. +merge.defaultToUpstream:: + If merge is called without any commit argument, merge the upstream + branches configured for the current branch by using their last + observed values stored in their remote tracking branches. + The values of the `branch.<current branch>.merge` that name the + branches at the remote named by `branch.<current branch>.remote` + are consulted, and then they are mapped via `remote.<remote>.fetch` + to their corresponding remote tracking branches, and the tips of + these tracking branches are merged. + 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 synonym for 20. merge.renameLimit:: The number of files to consider when performing rename detection @@ -31,10 +43,10 @@ merge.stat:: merge.tool:: Controls which merge resolution program is used by - linkgit:git-mergetool[1]. Valid built-in values are: "kdiff3", - "tkdiff", "meld", "xxdiff", "emerge", "vimdiff", "gvimdiff", - "diffuse", "ecmerge", "tortoisemerge", "p4merge", "araxis" and - "opendiff". Any other value is treated is custom merge tool + linkgit:git-mergetool[1]. Valid built-in values are: "araxis", + "bc3", "diffuse", "ecmerge", "emerge", "gvimdiff", "kdiff3", "meld", + "opendiff", "p4merge", "tkdiff", "tortoisemerge", "vimdiff" + and "xxdiff". Any other value is treated is custom merge tool and there must be a corresponding mergetool.<tool>.cmd option. merge.verbosity:: diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 722d704ff2..b613d4ed08 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. @@ -75,9 +75,17 @@ option can be used to override --squash. ifndef::git-pull[] -q:: --quiet:: - Operate quietly. + Operate quietly. Implies --no-progress. -v:: --verbose:: Be verbose. + +--progress:: +--no-progress:: + Turn progress on/off explicitly. If neither is specified, + progress is shown if standard error is connected to a terminal. + Note that not all merge strategies may support progress + reporting. + endif::git-pull[] diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index 8676e26ca2..595a3cf1a7 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,6 +74,10 @@ no-renormalize;; Disables the `renormalize` option. This overrides the `merge.renormalize` configuration variable. +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 diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 42ca059908..73111bb051 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -1,171 +1,17 @@ -Commit Formatting -~~~~~~~~~~~~~~~~~ - -ifdef::git-rev-list[] -Using these options, linkgit:git-rev-list[1] will act similar to the -more specialized family of commit log tools: linkgit:git-log[1], -linkgit:git-show[1], and linkgit:git-whatchanged[1] -endif::git-rev-list[] - -include::pretty-options.txt[] - ---relative-date:: - - Synonym for `--date=relative`. - ---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 - value for log command's --date option. -+ -`--date=relative` shows dates relative to the current time, -e.g. "2 hours ago". -+ -`--date=local` shows timestamps in user's local timezone. -+ -`--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format. -+ -`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 -format, often found in E-mail messages. -+ -`--date=short` shows only date but not time, in `YYYY-MM-DD` format. -+ -`--date=raw` shows the date in the internal raw git format `%s %z` format. -+ -`--date=default` shows timestamps in the original timezone -(either committer's or author's). - -ifdef::git-rev-list[] ---header:: - - Print the contents of the commit in raw-format; each record is - separated with a NUL character. -endif::git-rev-list[] - ---parents:: - - Print also the parents of the commit (in the form "commit parent..."). - Also enables parent rewriting, see 'History Simplification' below. - ---children:: - - Print also the children of the commit (in the form "commit child..."). - Also enables parent rewriting, see 'History Simplification' below. - -ifdef::git-rev-list[] ---timestamp:: - Print the raw commit timestamp. -endif::git-rev-list[] - ---left-right:: - - Mark which side of a symmetric diff a commit is reachable from. - Commits from the left side are prefixed with `<` and those from - the right with `>`. If combined with `--boundary`, those - commits are prefixed with `-`. -+ -For example, if you have this topology: -+ ------------------------------------------------------------------------ - y---b---b branch B - / \ / - / . - / / \ - o---x---a---a branch A ------------------------------------------------------------------------ -+ -you would get an output like this: -+ ------------------------------------------------------------------------ - $ git rev-list --left-right --boundary --pretty=oneline A...B - - >bbbbbbb... 3rd on b - >bbbbbbb... 2nd on b - <aaaaaaa... 3rd on a - <aaaaaaa... 2nd on a - -yyyyyyy... 1st on b - -xxxxxxx... 1st on a ------------------------------------------------------------------------ - ---graph:: - - Draw a text-based graphical representation of the commit history - on the left hand side of the output. This may cause extra lines - 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. - -ifdef::git-rev-list[] ---count:: - Print a number stating how many commits would have been - listed, and suppress all other output. When used together - with '--left-right', instead print the counts for left and - right commits, separated by a tab. -endif::git-rev-list[] - - -ifndef::git-rev-list[] -Diff Formatting -~~~~~~~~~~~~~~~ - -Below are listed options that control the formatting of diff output. -Some of them are specific to linkgit:git-rev-list[1], however other diff -options may be given. See linkgit:git-diff-files[1] for more options. - --c:: - - With this option, diff output for a merge commit - shows the differences from each of the parents to the merge result - simultaneously instead of showing pairwise diff between a parent - and the result one at a time. Furthermore, it lists only files - which were modified from all parents. - ---cc:: - - This flag implies the '-c' options and further compresses the - patch output by omitting uninteresting hunks whose contents in - the parents have only two variants and the merge result picks - one of them without modification. - --m:: - - This flag makes the merge commits show the full diff like - regular commits; for each merge parent, a separate log entry - and diff is generated. An exception is that only diff against - the first parent is shown when '--first-parent' option is given; - in that case, the output represents the changes the merge - brought _into_ the then-current branch. - --r:: - - Show recursive diffs. - --t:: - - Show the tree objects in the diff output. This implies '-r'. - --s:: - Suppress diff output. -endif::git-rev-list[] - Commit Limiting ~~~~~~~~~~~~~~~ Besides specifying a range of commits that should be listed using the special notations explained in the description, additional commit -limiting may be applied. +limiting may be applied. Note that they are applied before commit +ordering and formatting options, such as '--reverse'. -- -n 'number':: --max-count=<number>:: - Limit the number of commits output. + Limit the number of commits to output. --skip=<number>:: @@ -226,11 +72,26 @@ endif::git-rev-list[] --merges:: - Print only merge commits. + Print only merge commits. This is exactly the same as `--min-parents=2`. --no-merges:: - Do not print commits with more than one parent. + Do not print commits with more than one parent. This is + exactly the same as `--max-parents=1`. + +--min-parents=<number>:: +--max-parents=<number>:: +--no-min-parents:: +--no-max-parents:: + + Show only commits which have at least (or at most) that many + commits. In particular, `--max-parents=1` is the same as `--no-merges`, + `--min-parents=2` is the same as `--merges`. `--max-parents=0` + gives all root commits and `--min-parents=3` all octopus merges. ++ +`--no-min-parents` and `--no-max-parents` reset these limits (to no limit) +again. Equivalent forms are `--min-parents=0` (any commit has 0 or more +parents) and `--max-parents=-1` (negative numbers denote no upper limit). --first-parent:: Follow only the first parent commit upon seeing a merge @@ -269,7 +130,7 @@ endif::git-rev-list[] 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. + remote-tracking branches to ones matching given shell glob. If pattern lacks '?', '*', or '[', '/*' at the end is implied. --glob=<glob-pattern>:: @@ -305,6 +166,11 @@ ifdef::git-rev-list[] to /dev/null as the output does not have to be formatted. endif::git-rev-list[] +--cherry-mark:: + + Like `--cherry-pick` (see below) but mark equivalent commits + with `=` rather than omitting them, and inequivalent ones with `+`. + --cherry-pick:: Omit any commit that introduces the same change as @@ -313,12 +179,33 @@ endif::git-rev-list[] + For example, if you have two branches, `A` and `B`, a usual way to list all commits on only one side of them is with -`--left-right`, like the example above in the description of -that option. It however shows the commits that were cherry-picked +`--left-right` (see the example below in the description of +the `--left-right` option). It however shows the commits that were cherry-picked from the other branch (for example, "3rd on b" may be cherry-picked from branch A). With this option, such pairs of commits are excluded from the output. +--left-only:: +--right-only:: + + List only commits on the respective side of a symmetric range, + i.e. only those which would be marked `<` resp. `>` by + `--left-right`. ++ +For example, `--cherry-pick --right-only A...B` omits those +commits from `B` which are in `A` or are patch-equivalent to a commit in +`A`. In other words, this lists the `{plus}` commits from `git cherry A B`. +More precisely, `--cherry-pick --right-only --no-merges` gives the exact +list. + +--cherry:: + + A synonym for `--right-only --cherry-mark --no-merges`; useful to + limit the output to the commits on our side and mark those that + have been applied to the other side of a forked history with + `git log --cherry upstream...mybranch`, similar to + `git cherry upstream mybranch`. + -g:: --walk-reflogs:: @@ -735,3 +622,158 @@ These options are mostly targeted for packing of git repositories. --do-walk:: Overrides a previous --no-walk. + +Commit Formatting +~~~~~~~~~~~~~~~~~ + +ifdef::git-rev-list[] +Using these options, linkgit:git-rev-list[1] will act similar to the +more specialized family of commit log tools: linkgit:git-log[1], +linkgit:git-show[1], and linkgit:git-whatchanged[1] +endif::git-rev-list[] + +include::pretty-options.txt[] + +--relative-date:: + + Synonym for `--date=relative`. + +--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 + value for log command's --date option. ++ +`--date=relative` shows dates relative to the current time, +e.g. "2 hours ago". ++ +`--date=local` shows timestamps in user's local timezone. ++ +`--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format. ++ +`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 +format, often found in E-mail messages. ++ +`--date=short` shows only date but not time, in `YYYY-MM-DD` format. ++ +`--date=raw` shows the date in the internal raw git format `%s %z` format. ++ +`--date=default` shows timestamps in the original timezone +(either committer's or author's). + +ifdef::git-rev-list[] +--header:: + + Print the contents of the commit in raw-format; each record is + separated with a NUL character. +endif::git-rev-list[] + +--parents:: + + Print also the parents of the commit (in the form "commit parent..."). + Also enables parent rewriting, see 'History Simplification' below. + +--children:: + + Print also the children of the commit (in the form "commit child..."). + Also enables parent rewriting, see 'History Simplification' below. + +ifdef::git-rev-list[] +--timestamp:: + Print the raw commit timestamp. +endif::git-rev-list[] + +--left-right:: + + Mark which side of a symmetric diff a commit is reachable from. + Commits from the left side are prefixed with `<` and those from + the right with `>`. If combined with `--boundary`, those + commits are prefixed with `-`. ++ +For example, if you have this topology: ++ +----------------------------------------------------------------------- + y---b---b branch B + / \ / + / . + / / \ + o---x---a---a branch A +----------------------------------------------------------------------- ++ +you would get an output like this: ++ +----------------------------------------------------------------------- + $ git rev-list --left-right --boundary --pretty=oneline A...B + + >bbbbbbb... 3rd on b + >bbbbbbb... 2nd on b + <aaaaaaa... 3rd on a + <aaaaaaa... 2nd on a + -yyyyyyy... 1st on b + -xxxxxxx... 1st on a +----------------------------------------------------------------------- + +--graph:: + + Draw a text-based graphical representation of the commit history + on the left hand side of the output. This may cause extra lines + 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. + +ifdef::git-rev-list[] +--count:: + Print a number stating how many commits would have been + listed, and suppress all other output. When used together + with '--left-right', instead print the counts for left and + right commits, separated by a tab. +endif::git-rev-list[] + + +ifndef::git-rev-list[] +Diff Formatting +~~~~~~~~~~~~~~~ + +Below are listed options that control the formatting of diff output. +Some of them are specific to linkgit:git-rev-list[1], however other diff +options may be given. See linkgit:git-diff-files[1] for more options. + +-c:: + + With this option, diff output for a merge commit + shows the differences from each of the parents to the merge result + simultaneously instead of showing pairwise diff between a parent + and the result one at a time. Furthermore, it lists only files + which were modified from all parents. + +--cc:: + + This flag implies the '-c' options and further compresses the + patch output by omitting uninteresting hunks whose contents in + the parents have only two variants and the merge result picks + one of them without modification. + +-m:: + + This flag makes the merge commits show the full diff like + regular commits; for each merge parent, a separate log entry + and diff is generated. An exception is that only diff against + the first parent is shown when '--first-parent' option is given; + in that case, the output represents the changes the merge + brought _into_ the then-current branch. + +-r:: + + Show recursive diffs. + +-t:: + + Show the tree objects in the diff output. This implies '-r'. + +-s:: + Suppress diff output. +endif::git-rev-list[] diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 3d4b79c480..b290b617d4 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -1,134 +1,163 @@ SPECIFYING REVISIONS -------------------- -A revision parameter typically, but not necessarily, names a -commit object. They use what is called an 'extended SHA1' +A revision parameter '<rev>' typically, but not necessarily, names a +commit object. It uses what is called an 'extended SHA1' syntax. Here are various ways to spell object names. The -ones listed near the end of this list are to name trees and +ones listed near the end of this list name trees and blobs contained in a commit. -* The full SHA1 object name (40-byte hexadecimal string), or - a substring of such that is unique within the repository. +'<sha1>', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e':: + The full SHA1 object name (40-byte hexadecimal string), or + a leading substring that is unique within the repository. E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both - name the same commit object if there are no other object in + name the same commit object if there is no other object in your repository whose object name starts with dae86e. -* An output from 'git describe'; i.e. a closest tag, optionally +'<describeOutput>', e.g. 'v1.7.4.2-679-g3bee7fb':: + Output from `git describe`; i.e. a closest tag, optionally followed by a dash and a number of commits, followed by a dash, a - `g`, and an abbreviated object name. + 'g', and an abbreviated object name. -* A symbolic ref name. E.g. 'master' typically means the commit - object referenced by refs/heads/master. If you - happen to have both heads/master and tags/master, you can +'<refname>', e.g. 'master', 'heads/master', 'refs/heads/master':: + A symbolic ref name. E.g. 'master' typically means the commit + object referenced by 'refs/heads/master'. If you + happen to have both 'heads/master' and 'tags/master', you can explicitly say 'heads/master' to tell git which one you mean. - When ambiguous, a `<name>` is disambiguated by taking the + When ambiguous, a '<name>' is disambiguated by taking the first match in the following rules: - . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually - useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`); + . If '$GIT_DIR/<name>' exists, that is what you mean (this is usually + useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD' + and 'CHERRY_PICK_HEAD'); - . otherwise, `refs/<name>` if exists; + . otherwise, 'refs/<name>' if it exists; - . otherwise, `refs/tags/<name>` if exists; + . otherwise, 'refs/tags/<refname>' if it exists; - . otherwise, `refs/heads/<name>` if exists; + . otherwise, 'refs/heads/<name>' if it exists; - . otherwise, `refs/remotes/<name>` if exists; + . otherwise, 'refs/remotes/<name>' if it exists; - . otherwise, `refs/remotes/<name>/HEAD` if exists. + . otherwise, 'refs/remotes/<name>/HEAD' if it exists. + -HEAD names the commit your changes in the working tree is based on. -FETCH_HEAD records the branch you fetched from a remote repository -with your last 'git fetch' invocation. -ORIG_HEAD is created by commands that moves your HEAD in a drastic -way, to record the position of the HEAD before their operation, so that -you can change the tip of the branch back to the state before you ran -them easily. -MERGE_HEAD records the commit(s) you are merging into your branch -when you run 'git merge'. +'HEAD' names the commit on which you based the changes in the working tree. +'FETCH_HEAD' records the branch which you fetched from a remote repository +with your last `git fetch` invocation. +'ORIG_HEAD' is created by commands that move your 'HEAD' in a drastic +way, to record the position of the 'HEAD' before their operation, so that +you can easily change the tip of the branch back to the state before you ran +them. +'MERGE_HEAD' records the commit(s) which you are merging into your branch +when you run `git merge`. +'CHERRY_PICK_HEAD' records the commit which you are cherry-picking +when you run `git cherry-pick`. + -Note that any of the `refs/*` cases above may come either from -the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. +Note that any of the 'refs/*' cases above may come either from +the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file. -* A ref followed by the suffix '@' with a date specification +'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}':: + A ref followed by the suffix '@' with a date specification enclosed in a brace pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1 - second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value + second ago\}' or '\{1979-02-26 18:30:00\}') specifies the value of the ref at a prior point in time. This suffix may only be used immediately following a ref name and the ref must have an - existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state + existing log ('$GIT_DIR/logs/<ref>'). Note that this looks up the state of your *local* ref at a given time; e.g., what was in your local - `master` branch last week. If you want to look at commits made during - certain times, see `--since` and `--until`. + 'master' branch last week. If you want to look at commits made during + certain times, see '--since' and '--until'. -* A ref followed by the suffix '@' with an ordinal specification - enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify +'<refname>@\{<n>\}', e.g. 'master@\{1\}':: + A ref followed by the suffix '@' with an ordinal specification + enclosed in a brace pair (e.g. '\{1\}', '\{15\}') specifies the n-th prior value of that ref. For example 'master@\{1\}' is the immediate prior value of 'master' while 'master@\{5\}' is the 5th prior value of 'master'. This suffix may only be used immediately following a ref name and the ref must have an existing - log ($GIT_DIR/logs/<ref>). + log ('$GIT_DIR/logs/<refname>'). -* You can use the '@' construct with an empty ref part to get at a - reflog of the current branch. For example, if you are on the - branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'. +'@\{<n>\}', e.g. '@\{1\}':: + You can use the '@' construct with an empty ref part to get at a + reflog entry of the current branch. For example, if you are on + branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'. -* The special construct '@\{-<n>\}' means the <n>th branch checked out +'@\{-<n>\}', e.g. '@\{-1\}':: + The construct '@\{-<n>\}' means the <n>th branch checked out before the current one. -* The suffix '@\{upstream\}' to a ref (short form 'ref@\{u\}') refers to - the branch the ref is set to build on top of. Missing ref defaults +'<refname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: + The suffix '@\{upstream\}' to a ref (short form '<refname>@\{u\}') refers to + the branch the ref is set to build on top of. A missing ref defaults to the current branch. -* A suffix '{caret}' to a revision parameter (e.g. 'HEAD{caret}') means the first parent of +'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: + A suffix '{caret}' to a revision parameter means the first parent of that commit object. '{caret}<n>' means the <n>th parent (i.e. - 'rev{caret}' - is equivalent to 'rev{caret}1'). As a special rule, - 'rev{caret}0' means the commit itself and is used when 'rev' is the + '<rev>{caret}' + is equivalent to '<rev>{caret}1'). As a special rule, + '<rev>{caret}0' means the commit itself and is used when '<rev>' is the object name of a tag object that refers to a commit object. -* A suffix '{tilde}<n>' to a revision parameter means the commit +'<rev>{tilde}<n>', e.g. 'master{tilde}3':: + A suffix '{tilde}<n>' to a revision parameter means the commit object that is the <n>th generation grand-parent of the named - commit object, following only the first parent. I.e. rev~3 is - equivalent to rev{caret}{caret}{caret} which is equivalent to - rev{caret}1{caret}1{caret}1. See below for a illustration of + commit object, following only the first parents. I.e. '<rev>{tilde}3' is + equivalent to '<rev>{caret}{caret}{caret}' which is equivalent to + '<rev>{caret}1{caret}1{caret}1'. See below for an illustration of the usage of this form. -* A suffix '{caret}' followed by an object type name enclosed in - brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object +'<rev>{caret}\{<type>\}', e.g. 'v0.99.8{caret}\{commit\}':: + A suffix '{caret}' followed by an object type name enclosed in + brace pair means the object could be a tag, and dereference the tag recursively until an object of that type is found or the object cannot be - dereferenced anymore (in which case, barf). `rev{caret}0` - introduced earlier is a short-hand for `rev{caret}\{commit\}`. + dereferenced anymore (in which case, barf). '<rev>{caret}0' + is a short-hand for '<rev>{caret}\{commit\}'. -* A suffix '{caret}' followed by an empty brace pair - (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag, +'<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}':: + A suffix '{caret}' followed by an empty brace pair + means the object could be a tag, and dereference the tag recursively until a non-tag object is found. -* A colon, followed by a slash, followed by a text (e.g. `:/fix nasty bug`): this names +'<rev>{caret}\{/<text>\}', e.g. 'HEAD^{/fix nasty bug}':: + A suffix '{caret}' to a revision parameter, followed by a brace + pair that contains a text led by a slash, + is the same as the ':/fix nasty bug' syntax below except that + it returns the youngest matching commit which is reachable from + the '<rev>' before '{caret}'. + +':/<text>', e.g. ':/fix nasty bug':: + A colon, followed by a slash, followed by a text, names a commit whose commit message matches the specified regular expression. This name returns the youngest matching commit which is reachable from any ref. If the commit message starts with a - '!', you have to repeat that; the special sequence ':/!', - followed by something else than '!' is reserved for now. + '!' you have to repeat that; the special sequence ':/!', + followed by something else than '!', is reserved for now. The regular expression can match any part of the commit message. To - match messages starting with a string, one can use e.g. `:/^foo`. + match messages starting with a string, one can use e.g. ':/^foo'. -* A suffix ':' followed by a path (e.g. `HEAD:README`); this names the blob or tree +'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README':: + A suffix ':' followed by a path names the blob or tree at the given path in the tree-ish object named by the part before the colon. - ':path' (with an empty part before the colon, e.g. `:README`) + ':path' (with an empty part before the colon) is a special case of the syntax described next: content recorded in the index at the given path. - -* A colon, optionally followed by a stage number (0 to 3) and a - colon, followed by a path (e.g. `:0:README`); this names a blob object in the - index at the given path. Missing stage number (and the colon - that follows it, e.g. `:README`) names a stage 0 entry. During a merge, stage + A path starting with './' or '../' is relative to the current working directory. + The given path will be converted to be relative to the working tree's root directory. + This is most useful to address a blob or tree from a commit or tree that has + the same tree structure as the working tree. + +':<n>:<path>', e.g. ':0:README', ':README':: + A colon, optionally followed by a stage number (0 to 3) and a + colon, followed by a path, names a blob object in the + index at the given path. A missing stage number (and the colon + that follows it) names a stage 0 entry. During a merge, stage 1 is the common ancestor, stage 2 is the target branch's version (typically the current branch), and stage 3 is the version from - the branch being merged. + the branch which is being merged. Here is an illustration, by Jon Loeliger. Both commit nodes B and C are parents of commit node A. Parent commits are ordered @@ -162,31 +191,31 @@ G H I J SPECIFYING RANGES ----------------- -History traversing commands such as 'git log' operate on a set +History traversing commands such as `git log` operate on a set of commits, not just a single commit. To these commands, specifying a single revision with the notation described in the previous section means the set of commits reachable from that commit, following the commit ancestry chain. -To exclude commits reachable from a commit, a prefix `{caret}` -notation is used. E.g. `{caret}r1 r2` means commits reachable -from `r2` but exclude the ones reachable from `r1`. +To exclude commits reachable from a commit, a prefix '{caret}' +notation is used. E.g. '{caret}r1 r2' means commits reachable +from 'r2' but exclude the ones reachable from 'r1'. This set operation appears so often that there is a shorthand -for it. When you have two commits `r1` and `r2` (named according +for it. When you have two commits 'r1' and 'r2' (named according to the syntax explained in SPECIFYING REVISIONS above), you can ask for commits that are reachable from r2 excluding those that are reachable -from r1 by `{caret}r1 r2` and it can be written as `r1..r2`. +from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'. -A similar notation `r1\...r2` is called symmetric difference -of `r1` and `r2` and is defined as -`r1 r2 --not $(git merge-base --all r1 r2)`. +A similar notation 'r1\...r2' is called symmetric difference +of 'r1' and 'r2' and is defined as +'r1 r2 --not $(git merge-base --all r1 r2)'. It is the set of commits that are reachable from either one of -`r1` or `r2` but not from both. +'r1' or 'r2' but not from both. Two other shorthands for naming a set that is formed by a commit -and its parent commits exist. The `r1{caret}@` notation means all -parents of `r1`. `r1{caret}!` includes commit `r1` but excludes +and its parent commits exist. The 'r1{caret}@' notation means all +parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes all of its parents. Here are a handful of examples: diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt index a7e050bb7a..9dc1bed768 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 c5d141cd63..f6a4a361bd 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 index 535cdff164..9e1189ef01 100644 --- a/Documentation/technical/api-sigchain.txt +++ b/Documentation/technical/api-sigchain.txt @@ -32,7 +32,7 @@ and installation code should look something like: } ------------------------------------------ -Handlers are given the typdef of sigchain_fun. This is the same type +Handlers are given the typedef 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. diff --git a/Documentation/technical/index-format.txt b/Documentation/technical/index-format.txt new file mode 100644 index 0000000000..7b233ca196 --- /dev/null +++ b/Documentation/technical/index-format.txt @@ -0,0 +1,185 @@ +GIT index format +================ + += The git index file has the following format + + All binary numbers are in network byte order. Version 2 is described + here unless stated otherwise. + + - A 12-byte header consisting of + + 4-byte signature: + The signature is { 'D', 'I', 'R', 'C' } (stands for "dircache") + + 4-byte version number: + The current supported versions are 2 and 3. + + 32-bit number of index entries. + + - A number of sorted index entries (see below). + + - Extensions + + Extensions are identified by signature. Optional extensions can + be ignored if GIT does not understand them. + + GIT currently supports cached tree and resolve undo extensions. + + 4-byte extension signature. If the first byte is 'A'..'Z' the + extension is optional and can be ignored. + + 32-bit size of the extension + + Extension data + + - 160-bit SHA-1 over the content of the index file before this + checksum. + +== Index entry + + Index entries are sorted in ascending order on the name field, + interpreted as a string of unsigned bytes (i.e. memcmp() order, no + localization, no special casing of directory separator '/'). Entries + with the same name are sorted by their stage field. + + 32-bit ctime seconds, the last time a file's metadata changed + this is stat(2) data + + 32-bit ctime nanosecond fractions + this is stat(2) data + + 32-bit mtime seconds, the last time a file's data changed + this is stat(2) data + + 32-bit mtime nanosecond fractions + this is stat(2) data + + 32-bit dev + this is stat(2) data + + 32-bit ino + this is stat(2) data + + 32-bit mode, split into (high to low bits) + + 4-bit object type + valid values in binary are 1000 (regular file), 1010 (symbolic link) + and 1110 (gitlink) + + 3-bit unused + + 9-bit unix permission. Only 0755 and 0644 are valid for regular files. + Symbolic links and gitlinks have value 0 in this field. + + 32-bit uid + this is stat(2) data + + 32-bit gid + this is stat(2) data + + 32-bit file size + This is the on-disk size from stat(2), truncated to 32-bit. + + 160-bit SHA-1 for the represented object + + A 16-bit 'flags' field split into (high to low bits) + + 1-bit assume-valid flag + + 1-bit extended flag (must be zero in version 2) + + 2-bit stage (during merge) + + 12-bit name length if the length is less than 0xFFF; otherwise 0xFFF + is stored in this field. + + (Version 3) A 16-bit field, only applicable if the "extended flag" + above is 1, split into (high to low bits). + + 1-bit reserved for future + + 1-bit skip-worktree flag (used by sparse checkout) + + 1-bit intent-to-add flag (used by "git add -N") + + 13-bit unused, must be zero + + Entry path name (variable length) relative to top level directory + (without leading slash). '/' is used as path separator. The special + path components ".", ".." and ".git" (without quotes) are disallowed. + Trailing slash is also disallowed. + + The exact encoding is undefined, but the '.' and '/' characters + are encoded in 7-bit ASCII and the encoding cannot contain a NUL + byte (iow, this is a UNIX pathname). + + 1-8 nul bytes as necessary to pad the entry to a multiple of eight bytes + while keeping the name NUL-terminated. + +== Extensions + +=== Cached tree + + Cached tree extension contains pre-computed hashes for trees that can + be derived from the index. It helps speed up tree object generation + from index for a new commit. + + When a path is updated in index, the path must be invalidated and + removed from tree cache. + + The signature for this extension is { 'T', 'R', 'E', 'E' }. + + A series of entries fill the entire extension; each of which + consists of: + + - NUL-terminated path component (relative to its parent directory); + + - ASCII decimal number of entries in the index that is covered by the + tree this entry represents (entry_count); + + - A space (ASCII 32); + + - ASCII decimal number that represents the number of subtrees this + tree has; + + - A newline (ASCII 10); and + + - 160-bit object name for the object that would result from writing + this span of index as a tree. + + An entry can be in an invalidated state and is represented by having -1 + in the entry_count field. + + The entries are written out in the top-down, depth-first order. The + first entry represents the root level of the repository, followed by the + first subtree---let's call this A---of the root level (with its name + relative to the root level), followed by the first subtree of A (with + its name relative to A), ... + +=== Resolve undo + + A conflict is represented in the index as a set of higher stage entries. + When a conflict is resolved (e.g. with "git add path"), these higher + stage entries will be removed and a stage-0 entry with proper resoluton + is added. + + When these higher stage entries are removed, they are saved in the + resolve undo extension, so that conflicts can be recreated (e.g. with + "git checkout -m"), in case users want to redo a conflict resolution + from scratch. + + The signature for this extension is { 'R', 'E', 'U', 'C' }. + + A series of entries fill the entire extension; each of which + consists of: + + - NUL-terminated pathname the entry describes (relative to the root of + the repository, i.e. full pathname); + + - Three NUL-terminated ASCII octal numbers, entry mode of entries in + stage 1 to 3 (a missing stage is represented by "0" in this field); + and + + - At most three 160-bit object names of the entry in stages from 1 to 3 + (nothing is written for a missing stage). + diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index fc56da677c..f13a846131 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. @@ -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 @@ -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 @@ -2800,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 |