diff options
Diffstat (limited to 'Documentation')
31 files changed, 814 insertions, 147 deletions
diff --git a/Documentation/RelNotes-1.7.1.1.txt b/Documentation/RelNotes-1.7.1.1.txt new file mode 100644 index 0000000000..e0386a43f0 --- /dev/null +++ b/Documentation/RelNotes-1.7.1.1.txt @@ -0,0 +1,67 @@ +Git v1.7.1.1 Release Notes (draft) +================================== + +Fixes since v1.7.1 +------------------ + + * Authentication over http transport can now be made lazily, in that the + request can first go to a URL without username, get a 401 response and + then the client will ask for the username to use. + + * We used to mistakenly think "../work" is a subdirectory of the current + directory when we are in "../work-xyz". + + * The attribute mechanism now allows an entry that uses an attribute + macro that set/unset one attribute, immediately followed by an + overriding setting; this makes attribute macros much easier to use. + + * We didn't recognize timezone "Z" as a synonym for "UTC" (75b37e70). + + * "git am -3" did not show diagnosis when the patch in the message was corrupt. + + * After "git apply --whitespace=fix" removed trailing blank lines in an + patch in a patch series, it failed to apply later patches that depend + on the presense of such blank lines. + + * "git bundle --stdin" segfaulted. + + * "git checkout" and "git rebase" overwrote paths that are marked "assume + unchanged". + + * "git describe" did not tie-break tags that point at the same commit + correctly; newer ones are preferred by paying attention to the + tagger date now. + + * "git diff" used to tell underlying xdiff machinery to work very hard to + minimize the output, but this often was spending too many extra cycles + for very little gain. + + * "git diff --color" did not paint extended diff headers per line + (i.e. the coloring escape sequence didn't end at the end of line), + which confused "less -R". + + * "git fetch" over HTTP verifies the downloaded packfiles more robustly. + + * The memory usage by "git index-pack" (run during "git fetch" and "git + push") got leaner. + + * "GIT_DIR=foo.git git init --bare bar.git" created foo.git instead of bar.git. + + * "git log --abbrev=$num --format='%h' ignored --abbrev=$num. + + * "git pull" accepted "--dry-run", gave it to underlying "git fetch" but + ignored the option itself, resulting in a bogus attempt to merge + unrelated commit. + + * "git send-email" lacked a way to specify the domainname used in the + EHLO/HELO exchange, causing rejected connection from picky servers. + It learned --smtp-domain option to solve this issue. + + * "git stash" incorrectly lost paths in the working tree that were + previously removed from the index. + + * "git status" stopped refreshing the index by mistake in 1.7.1. + + * "git status" showed excess "hints" even when advice.statusHints is set to false. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes-1.7.2.txt b/Documentation/RelNotes-1.7.2.txt new file mode 100644 index 0000000000..a1b5428df4 --- /dev/null +++ b/Documentation/RelNotes-1.7.2.txt @@ -0,0 +1,115 @@ +Git v1.7.2 Release Notes (draft) +================================ + +Updates since v1.7.1 +-------------------- + + * The whitespace rules used in "git apply --whitespace" and "git diff" + gained a new member in the family (tab-in-indent) to help projects with + policy to indent only with spaces. + + * When working from a subdirectory, by default, git does not look for its + metadirectory ".git" across filesystems, primarily to help people who + have invocations of git in their custom PS1 prompts, as being outside + of a git repository would look for ".git" all the way up to the root + directory, and NFS mounts are often slow. DISCOVERY_ACROSS_FILESYSTEM + environment variable can be used to tell git not to stop at a + filesystem boundary. + + * "git" wrapper learned "-c name=value" option to override configuration + variable from the command line. + + * The message from "git am -3" has been improved when conflict + resolution ended up making the patch a no-op. + + * "git checkout --orphan newbranch" is similar to "-b newbranch" but + prepares to create a root commit that is not connected to any existing + commit. + + * "git commit --amend" on a commit with an invalid author-name line that + lacks the display name didn't work (fb7749e4). + + * "git cvsserver" can be told to use pserver; its password file can be + stored outside the repository. + + * The output from the textconv filter used by "git diff" can be cached to + speed up their reuse. + + * "git diff --word-diff=<mode>" extends the existing "--color-words" + option, making it more useful in color-challenged environments. + + * The regexp to detect function headers used by "git diff" for PHP has + been enhanced for visibility modifiers (public, protected, etc.) to + better support PHP5. + + * "diff.noprefix" configuration variable can be used to implicitly + ask for "diff --no-prefix" behaviour. + + * "git for-each-ref" learned "%(objectname:short)" that gives the object + name abbreviated. + + * Various options to "git grep" (e.g. --count, --name-only) work better + with binary files. + + * "git help -w" learned "chrome" and "chromium" browsers. + + * "git log --follow <path>" follows across copies (it used to only follow + renames). This may make the processing more expensive. + + * "git ls-files ../out/side/cwd" works now. + + * "git notes prune" learned "-n" (dry-run) and "-v" options, similar to + what "git prune" has. + + * "git patch-id" can be fed a mbox without getting confused by the + signature line in the format-patch output. + + * "git remote" learned "set-branches" subcommand. + + * "git revert" learned --strategy option to specify the merge strategy. + + * "git status [-s] --ignored" can be used to list ignored paths. + + * "git status -s -b" shows the current branch in the output. + + * Various "gitweb" enhancements and clean-ups, including syntax + highlighting, "plackup" support for instaweb, etc. + + +Fixes since v1.7.1 +------------------ + +All of the fixes in v1.7.1.X maintenance series are included in this +release, unless otherwise noted. + + * We didn't URL decode "file:///path/to/repo" correctly when path/to/repo + had percent-encoded characters (638794c, 9d2e942). + + * "git clone/fetch/pull" issued an incorrect error message when a ref and + a symref that points to the ref were updated at the same time. This + obviously would update them to the same value, and should not result in + an error condition (7223dcaf). + + * "git clone" did not configure remote.origin.url correctly for bare + clones (df61c889). + + * "git diff --graph" works better with "--color-words" and other options + (81fa024..4297c0a). + + * "git diff" could show ambiguous abbreviation of blob object names on + its "index" line (3e5a188). + + * "git merge --log" used to replace the custom message given by "-m" with + the shortlog, instead of appending to it (tc/merge-m-log). + + * "git reset --hard" started from a wrong directory and a working tree in + a nonstandard location is in use got confused (560fb6a1). + + * "git show -C -C" and other corner cases lost diff metainfo output + in 1.7.0 (296c6bb). + +-- +exec >/var/tmp/1 +O=v1.7.1-423-gae391ec +echo O=$(git describe HEAD) +git shortlog --no-merges HEAD ^maint ^$O diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index abc65de946..eb53e0636e 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -41,6 +41,7 @@ Checklist (and a short version for the impatient): maintainer (gitster@pobox.com) if (and only if) the patch is ready for inclusion. If you use git-send-email(1), please test it first by sending email to yourself. + - see below for instructions specific to your mailer Long version: @@ -53,6 +54,34 @@ But the patch submission requirements are a lot more relaxed here on the technical/contents front, because the core GIT is thousand times smaller ;-). So here is only the relevant bits. +(0) Decide what to base your work on. + +In general, always base your work on the oldest branch that your +change is relevant to. + + - A bugfix should be based on 'maint' in general. If the bug is not + present in 'maint', base it on 'master'. For a bug that's not yet + in 'master', find the topic that introduces the regression, and + base your work on the tip of the topic. + + - A new feature should be based on 'master' in general. If the new + feature depends on a topic that is in 'pu', but not in 'master', + base your work on the tip of that topic. + + - Corrections and enhancements to a topic not yet in 'master' should + be based on the tip of that topic. If the topic has not been merged + to 'next', it's alright to add a note to squash minor corrections + into the series. + + - In the exceptional case that a new feature depends on several topics + not in 'master', start working on 'next' or 'pu' privately and send + out patches for discussion. Before the final merge, you may have to + wait until some of the dependent topics graduate to 'master', and + rebase your work. + +To find the tip of a topic branch, run "git log --first-parent +master..pu" and look for the merge commit. The second parent of this +commit is the tip of the topic branch. (1) Make separate commits for logically separate changes. @@ -170,17 +199,16 @@ patch, format it as "multipart/signed", not a text/plain message that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is not a text/plain, it's something else. -Note that your maintainer does not necessarily read everything -on the git mailing list. If your patch is for discussion first, -send it "To:" the mailing list, and optionally "cc:" him. If it -is trivially correct or after the list reached a consensus, send -it "To:" the maintainer and optionally "cc:" the list for -inclusion. - -Also note that your maintainer does not actively involve himself in -maintaining what are in contrib/ hierarchy. When you send fixes and -enhancements to them, do not forget to "cc: " the person who primarily -worked on that hierarchy in contrib/. +Unless your patch is a very trivial and an obviously correct one, +first send it with "To:" set to the mailing list, with "cc:" listing +people who are involved in the area you are touching (the output from +"git blame $path" and "git shortlog --no-merges $path" would help to +identify them), to solicit comments and reviews. After the list +reached a consensus that it is a good idea to apply the patch, re-send +it with "To:" set to the maintainer and optionally "cc:" the list for +inclusion. Do not forget to add trailers such as "Acked-by:", +"Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as +necessary. (4) Sign your work @@ -519,9 +547,27 @@ Gmail GMail does not appear to have any way to turn off line wrapping in the web interface, so this will mangle any emails that you send. You can however -use any IMAP email client to connect to the google imap server, and forward +use "git send-email" and send your patches through the GMail SMTP server, or +use any IMAP email client to connect to the google IMAP server and forward the emails through that. +To use "git send-email" and send your patches through the GMail SMTP server, +edit ~/.gitconfig to specify your account settings: + +[sendemail] + smtpencryption = tls + smtpserver = smtp.gmail.com + smtpuser = user@gmail.com + smtppass = p4ssw0rd + smtpserverport = 587 + +Once your commits are ready to be sent to the mailing list, run the +following commands: + + $ git format-patch --cover-letter -M origin/master -o outgoing/ + $ edit outgoing/0000-* + $ git send-email outgoing/* + To submit using the IMAP interface, first, edit your ~/.gitconfig to specify your account settings: @@ -537,8 +583,7 @@ You might need to instead use: folder = "[Google Mail]/Drafts" if you get an err that the "Folder doesn't exist". Once your commits are ready to be sent to the mailing list, run the -following command to send the patch emails to your Gmail Drafts -folder. +following commands: $ git format-patch --cover-letter -M --stdout origin/master | git imap-send @@ -546,19 +591,3 @@ 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). -Alternatively, you can use "git send-email" and send your patches -through the GMail SMTP server. edit ~/.gitconfig to specify your -account settings: - -[sendemail] - smtpencryption = tls - smtpserver = smtp.gmail.com - smtpuser = user@gmail.com - smtppass = p4ssw0rd - smtpserverport = 587 - -Once your commits are ready to be sent to the mailing list, run the -following commands: - - $ git format-patch --cover-letter -M origin/master -o outgoing/ - $ git send-email outgoing/* diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index d8205691c6..16e3c68576 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -90,9 +90,9 @@ of lines before or after the line given by <start>. running extra passes of inspection. + <num> is optional but it is the lower bound on the number of -alphanumeric characters that git must detect as moving +alphanumeric characters that git must detect as moving/copying within a file for it to associate those lines with the parent -commit. +commit. The default value is 20. -C|<num>|:: In addition to `-M`, detect lines moved or copied from other @@ -105,9 +105,11 @@ commit. looks for copies from other files in any commit. + <num> is optional but it is the lower bound on the number of -alphanumeric characters that git must detect as moving +alphanumeric characters that git must detect as moving/copying between files for it to associate those lines with the parent -commit. +commit. And the default value is 40. If there are more than one +`-C` options given, the <num> argument of the last `-C` will +take effect. -h:: --help:: diff --git a/Documentation/config.txt b/Documentation/config.txt index 92f851e797..7afd0a333f 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -481,6 +481,8 @@ core.whitespace:: error (enabled by default). * `indent-with-non-tab` treats a line that is indented with 8 or more space characters as an error (not enabled by default). +* `tab-in-indent` treats a tab character in the initial indent part of + the line as an error (not enabled by default). * `blank-at-eof` treats blank lines added at the end of file as an error (enabled by default). * `trailing-space` is a short-hand to cover both `blank-at-eol` and @@ -518,18 +520,12 @@ check that makes sure that existing object files will not get overwritten. core.notesRef:: When showing commit messages, also show notes which are stored in - the given ref. This ref is expected to contain files named - after the full SHA-1 of the commit they annotate. The ref - must be fully qualified. + the given ref. The ref must be fully qualified. If the given + ref does not exist, it is not an error but means that no + notes should be printed. + -If such a file exists in the given ref, the referenced blob is read, and -appended to the commit message, separated by a "Notes (<refname>):" -line (shortened to "Notes:" in the case of "refs/notes/commits"). If the -given ref itself does not exist, it is not an error, but means that no -notes should be printed. -+ -This setting defaults to "refs/notes/commits", and can be overridden by -the `GIT_NOTES_REF` environment variable. +This setting defaults to "refs/notes/commits", and it can be overridden by +the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1]. core.sparseCheckout:: Enable "sparse checkout" feature. See section "Sparse checkout" in @@ -796,6 +792,8 @@ diff.mnemonicprefix:: standard "a/" and "b/" depending on what is being compared. When this configuration is in effect, reverse diff output also swaps the order of the prefixes: +diff.noprefix:: + If set, 'git diff' does not show any source or destination prefix. `git diff`;; compares the (i)ndex and the (w)ork tree; `git diff HEAD`;; @@ -944,13 +942,19 @@ gc.pruneexpire:: unreachable objects immediately. gc.reflogexpire:: +gc.<pattern>.reflogexpire:: 'git reflog expire' removes reflog entries older than - this time; defaults to 90 days. + this time; defaults to 90 days. With "<pattern>" (e.g. + "refs/stash") in the middle the setting applies only to + the refs that match the <pattern>. gc.reflogexpireunreachable:: +gc.<ref>.reflogexpireunreachable:: 'git reflog expire' removes reflog entries older than this time and are not reachable from the current tip; - defaults to 30 days. + defaults to 30 days. With "<pattern>" (e.g. "refs/stash") + in the middle, the setting applies only to the refs that + match the <pattern>. gc.rerereresolved:: Records of conflicted merge you resolved earlier are @@ -1268,6 +1272,13 @@ log.date:: following alternatives: {relative,local,default,iso,rfc,short}. See linkgit:git-log[1]. +log.decorate:: + Print out the ref names of any commits that are shown by the log + command. If 'short' is specified, the ref name prefixes 'refs/heads/', + 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is + specified, the full ref name (including prefix) will be printed. + This is the same as the log commands '--decorate' option. + log.showroot:: If true, the initial commit will be shown as a big creation event. This is equivalent to a diff against an empty tree. @@ -1359,10 +1370,6 @@ notes.rewrite.<command>:: automatically copies your notes from the original to the rewritten commit. Defaults to `true`, but see "notes.rewriteRef" below. -+ -This setting can be overridden with the `GIT_NOTES_REWRITE_REF` -environment variable, which must be a colon separated list of refs or -globs. notes.rewriteMode:: When copying notes during a rewrite (see the @@ -1382,6 +1389,10 @@ notes.rewriteRef:: + Does not have a default value; you must configure this variable to enable note rewriting. ++ +This setting can be overridden with the `GIT_NOTES_REWRITE_REF` +environment variable, which must be a colon separated list of refs or +globs. pack.window:: The size of the window used by linkgit:git-pack-objects[1] when no @@ -1466,6 +1477,16 @@ pager.<cmd>:: 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 + linkgit:git-log[1]. Any aliases defined here can be used just + as the built-in pretty formats could. For example, + running `git config pretty.changelog "format:{asterisk} %H %s"` + would cause the invocation `git log --pretty=changelog` + to be equivalent to running `git log "--pretty=format:{asterisk} %H %s"`. + Note that an alias with the same name as a built-in format + will be silently ignored. + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. @@ -1516,7 +1537,7 @@ receive.denyDeletes:: the ref. Use this to prevent such a ref deletion via a push. receive.denyCurrentBranch:: - If set to true or "refuse", receive-pack will deny a ref update + If set to true or "refuse", git-receive-pack will deny a ref update to the currently checked out branch of a non-bare repository. Such a push is potentially dangerous because it brings the HEAD out of sync with the index and working tree. If set to "warn", @@ -1578,7 +1599,9 @@ remote.<name>.uploadpack:: remote.<name>.tagopt:: Setting this value to \--no-tags disables automatic tag following when - fetching from remote <name> + fetching from remote <name>. Setting it to \--tags will fetch every + tag from remote <name>, even if they are not reachable from remote + branch heads. remote.<name>.vcs:: Setting this to a value <vcs> will cause git to interact with @@ -1642,6 +1665,7 @@ sendemail.smtppass:: sendemail.suppresscc:: sendemail.suppressfrom:: sendemail.to:: +sendemail.smtpdomain:: sendemail.smtpserver:: sendemail.smtpserverport:: sendemail.smtpuser:: @@ -1681,6 +1705,13 @@ If this variable is not specified, it defaults to 'normal'. This variable can be overridden with the -u|--untracked-files option of linkgit:git-status[1] and linkgit:git-commit[1]. +status.submodulesummary:: + Defaults to false. + If this is set to a non zero number or true (identical to -1 or an + unlimited number), the submodule summary will be enabled and a + summary of commits for modified submodules will be shown (see + --summary-limit option of linkgit:git-submodule[1]). + tar.umask:: This variable can be used to restrict the permission bits of tar archive entries. The default is 0002, which turns off the diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index c9c6c2b1cb..e745a3ccdc 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -21,6 +21,7 @@ endif::git-format-patch[] ifndef::git-format-patch[] -p:: -u:: +--patch:: Generate patch (see section on generating patches). {git-diff? This is the default.} endif::git-format-patch[] @@ -126,11 +127,39 @@ any of those replacements occurred. gives the default to color output. Same as `--color=never`. ---color-words[=<regex>]:: - Show colored word diff, i.e., color words which have changed. - By default, words are separated by whitespace. +--word-diff[=<mode>]:: + Show a word diff, using the <mode> to delimit changed words. + By default, words are delimited by whitespace; see + `--word-diff-regex` below. The <mode> defaults to 'plain', and + must be one of: ++ +-- +color:: + Highlight changed words using only colors. Implies `--color`. +plain:: + Show words as `[-removed-]` and `{+added+}`. Makes no + attempts to escape the delimiters if they appear in the input, + so the output may be ambiguous. +porcelain:: + Use a special line-based format intended for script + consumption. Added/removed/unchanged runs are printed in the + usual unified diff format, starting with a `+`/`-`/` ` + character at the beginning of the line and extending to the + end of the line. Newlines in the input are represented by a + tilde `~` on a line of its own. +none:: + Disable word diff again. +-- + -When a <regex> is specified, every non-overlapping match of the +Note that despite the name of the first mode, color is used to +highlight the changed parts in all modes if enabled. + +--word-diff-regex=<regex>:: + Use <regex> to decide what a word is, instead of considering + runs of non-whitespace to be a word. Also implies + `--word-diff` unless it was already enabled. ++ +Every non-overlapping match of the <regex> is considered a word. Anything between these matches is considered whitespace and ignored(!) for the purposes of finding differences. You may want to append `|[^[:space:]]` to your regular @@ -142,6 +171,10 @@ The regex can also be set via a diff driver or configuration option, see linkgit:gitattributes[1] or linkgit:git-config[1]. Giving it explicitly overrides any diff driver or configuration setting. Diff drivers override configuration settings. + +--color-words[=<regex>]:: + Equivalent to `--word-diff=color` plus (if a regex was + specified) `--word-diff-regex=<regex>`. endif::git-format-patch[] --no-renames:: @@ -177,7 +210,14 @@ endif::git-format-patch[] Break complete rewrite changes into pairs of delete and create. -M:: +ifndef::git-log[] Detect renames. +endif::git-log[] +ifdef::git-log[] + If generating diffs, detect and report renames for each commit. + For following files across renames while traversing history, see + `--follow`. +endif::git-log[] -C:: Detect copies as well as renames. See also `--find-copies-harder`. diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 51cbeb7032..74741a42f4 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -266,9 +266,9 @@ patch:: y - stage this hunk n - do not stage this hunk - q - quit, do not stage this hunk nor any of the remaining ones - a - stage this and all the remaining hunks in the file - d - do not stage this hunk nor any of the remaining hunks in the file + q - quit; do not stage this hunk nor any of the remaining ones + a - stage this hunk and all later hunks in the file + d - do not stage this hunk nor any of the later hunks in the file g - select a hunk to go to / - search for a hunk matching the given regex j - leave this hunk undecided, see next undecided hunk diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 37c1810e3f..261dd90c38 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -9,39 +9,47 @@ SYNOPSIS -------- [verse] 'git checkout' [-q] [-f] [-m] [<branch>] -'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>] +'git checkout' [-q] [-f] [-m] [[-b|--orphan] <new_branch>] [<start_point>] 'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>... 'git checkout' --patch [<tree-ish>] [--] [<paths>...] DESCRIPTION ----------- - -When <paths> are not given, this command switches branches by -updating the index, working tree, and HEAD to reflect the specified +Updates files in the working tree to match the version in the index +or the specified tree. If no paths are given, 'git checkout' will +also update `HEAD` to set the specified branch as the current branch. -If `-b` is given, a new branch is created and checked out, as if -linkgit:git-branch[1] were called; in this case you can -use the --track or --no-track options, which will be passed to `git -branch`. As a convenience, --track without `-b` implies branch -creation; see the description of --track below. - -When <paths> or --patch are given, this command does *not* switch -branches. It updates the named paths in the working tree from -the index file, or from a named <tree-ish> (most often a commit). In -this case, the `-b` and `--track` options are meaningless and giving -either of them results in an error. The <tree-ish> argument can be -used to specify a specific tree-ish (i.e. commit, tag or tree) -to update the index for the given paths before updating the -working tree. - -The index may contain unmerged entries after a failed merge. By -default, if you try to check out such an entry from the index, the +'git checkout' [<branch>]:: +'git checkout' -b <new branch> [<start point>]:: + + This form switches branches by updating the index, working + tree, and HEAD to reflect the specified branch. ++ +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 +use the `--track` or `--no-track` options, which will be passed to +'git branch'. As a convenience, `--track` without `-b` implies branch +creation; see the description of `--track` below. + +'git checkout' [--patch] [<tree-ish>] [--] <pathspec>...:: + + When <paths> or `--patch` are given, 'git checkout' *not* switch + branches. It updates the named paths in the working tree from + the index file or from a named <tree-ish> (most often a commit). In + this case, the `-b` and `--track` options are meaningless and giving + either of them results in an error. The <tree-ish> argument can be + used to specify a specific tree-ish (i.e. commit, tag or tree) + to update the index for the given paths before updating the + working tree. ++ +The index may contain unmerged entries because of a previous failed merge. +By default, if you try to check out such an entry from the index, the checkout operation will fail and nothing will be checked out. -Using -f will ignore these unmerged entries. The contents from a +Using `-f` will ignore these unmerged entries. The contents from a specific side of the merge can be checked out of the index by -using --ours or --theirs. With -m, changes made to the working tree -file can be discarded to recreate the original conflicted merge result. +using `--ours` or `--theirs`. With `-m`, changes made to the working tree +file can be discarded to re-create the original conflicted merge result. OPTIONS ------- @@ -90,6 +98,31 @@ explicitly give a name with '-b' in such a case. Create the new branch's reflog; see linkgit:git-branch[1] 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 + new branch will have no parents and it will be the root of a new + history totally disconnected from all the other branches and + commits. ++ +The index and the working tree are adjusted as if you had previously run +"git checkout <start_point>". This allows you to start a new history +that records a set of paths similar to <start_point> by easily running +"git commit -a" to make the root commit. ++ +This can be useful when you want to publish the tree from a commit +without exposing its full history. You might want to do this to publish +an open source branch of a project whose current tree is "clean", but +whose full history contains proprietary or otherwise encumbered bits of +code. ++ +If you want to start a disconnected history that records a set of paths +that is totally different from the one of <start_point>, then you should +clear the index and the working tree right after creating the orphan +branch by running "git rm -rf ." from the top level of the working tree. +Afterwards you will be ready to prepare your new files, repopulating the +working tree, by copying them from elsewhere, extracting a tarball, etc. + -m:: --merge:: When switching branches, @@ -136,6 +169,10 @@ edits from your current working tree. As a special case, the `"@\{-N\}"` syntax for the N-th last branch checks out the branch (instead of detaching). You may also specify `-` which is synonymous with `"@\{-1\}"`. ++ +As a further special case, you may use `"A...B"` as a shortcut for the +merge base of `A` and `B` if there is exactly one merge base. You can +leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. <new_branch>:: Name for the new branch. diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 64fb458b45..c28603ecf5 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -10,7 +10,7 @@ SYNOPSIS [verse] 'git commit' [-a | --interactive] [-s] [-v] [-u<mode>] [--amend] [--dry-run] [(-c | -C) <commit>] [-F <file> | -m <msg>] [--reset-author] - [--allow-empty] [--no-verify] [-e] [--author=<author>] + [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=<author>] [--date=<date>] [--cleanup=<mode>] [--status | --no-status] [--] [[-i | -o ]<file>...] @@ -95,10 +95,11 @@ OPTIONS read the message from the standard input. --author=<author>:: - Override the author name used in the commit. You can use the - standard `A U Thor <author@example.com>` format. Otherwise, - an existing commit that matches the given string and its author - name is used. + Override the commit author. Specify an explicit author using the + standard `A U Thor <author@example.com>` format. Otherwise <author> + is assumed to be a pattern and is used to search for an existing + commit by that author (i.e. rev-list --all -i --author=<author>); + the commit author is then copied from the first such commit found. --date=<date>:: Override the author date used in the commit. @@ -131,6 +132,12 @@ OPTIONS from making such a commit. This option bypasses the safety, and is primarily for use by foreign scm interface scripts. +--allow-empty-message:: + Like --allow-empty this command is primarily for use by foreign + scm interface scripts. It allows you to create a commit with an + empty commit message without using plumbing commands like + linkgit:git-commit-tree[1]. + --cleanup=<mode>:: This option sets how the commit message is cleaned up. The '<mode>' can be one of 'verbatim', 'whitespace', 'strip', diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index dbb053ee17..c27ca4350e 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -72,9 +72,6 @@ plugin. Most functionality works fine with both of these clients. LIMITATIONS ----------- -Currently cvsserver works over SSH connections for read/write clients, and -over pserver for anonymous CVS access. - CVS clients cannot tag, branch or perform GIT merges. 'git-cvsserver' maps GIT branches to CVS modules. This is very different @@ -84,7 +81,7 @@ one or more directories. INSTALLATION ------------ -1. If you are going to offer anonymous CVS access via pserver, add a line in +1. If you are going to offer CVS access via pserver, add a line in /etc/inetd.conf like + -- @@ -101,6 +98,38 @@ looks like cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver ------ + +Only anonymous access is provided by pserve by default. To commit you +will have to create pserver accounts, simply add a gitcvs.authdb +setting in the config file of the repositories you want the cvsserver +to allow writes to, for example: + +------ + + [gitcvs] + authdb = /etc/cvsserver/passwd + +------ +The format of these files is username followed by the crypted password, +for example: + +------ + myuser:$1Oyx5r9mdGZ2 + myuser:$1$BA)@$vbnMJMDym7tA32AamXrm./ +------ +You can use the 'htpasswd' facility that comes with Apache to make these +files, but Apache's MD5 crypt method differs from the one used by most C +library's crypt() function, so don't use the -m option. + +Alternatively you can produce the password with perl's crypt() operator: +----- + perl -e 'my ($user, $pass) = @ARGV; printf "%s:%s\n", $user, crypt($user, $pass)' $USER password +----- + +Then provide your password via the pserver method, for example: +------ + cvs -d:pserver:someuser:somepassword <at> server/path/repo.git co <HEAD_name> +------ No special setup is needed for SSH access, other than having GIT tools in the PATH. If you have clients that do not accept the CVS_SERVER environment variable, you can rename 'git-cvsserver' to `cvs`. diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 7e83288d18..390d85ccae 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -86,6 +86,7 @@ objectsize:: objectname:: The object name (aka SHA-1). + For a non-ambiguous abbreviation of the object name append `:short`. upstream:: The name of a local ref which can be considered ``upstream'' diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 189573a3b3..a9e0882e9b 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -88,6 +88,16 @@ commits prior to the amend or rebase occurring. Since these changes 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 +branches: + +------------ +[gc "refs/remotes/*"] + reflogExpire = never + reflogexpireUnreachable = 3 days +------------ + The optional configuration variable 'gc.rerereresolved' indicates how long records of conflicted merge you resolved earlier are kept. This defaults to 60 days. diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index a1f17df074..2c3c4d2994 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -29,7 +29,7 @@ OPTIONS The HTTP daemon command-line that will be executed. Command-line options may be specified here, and the configuration file will be added at the end of the command-line. - Currently apache2, lighttpd, mongoose and webrick are supported. + Currently apache2, lighttpd, mongoose, plackup and webrick are supported. (Default: lighttpd) -m:: diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index fb184ba186..0e6ff31823 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -37,7 +37,8 @@ include::diff-options.txt[] and <until>, see "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. ---decorate[=short|full]:: +--no-decorate:: +--decorate[=short|full|no]:: Print out the ref names of any commits that are shown. If 'short' is specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is specified, the @@ -56,7 +57,7 @@ include::diff-options.txt[] commits, and doesn't limit diff for those commits. --follow:: - Continue listing the history of a file beyond renames. + Continue listing the history of a file beyond renames/copies. --log-size:: Before the log message print out its size in bytes. Intended @@ -132,6 +133,48 @@ Discussion include::i18n.txt[] +Configuration +------------- + +See linkgit:git-config[1] for core variables and linkgit:git-diff[1] +for settings related to diff generation. + +format.pretty:: + Default for the `--format` option. (See "PRETTY FORMATS" above.) + Defaults to "medium". + +i18n.logOutputEncoding:: + Encoding to use when displaying logs. (See "Discussion", above.) + Defaults to the value of `i18n.commitEncoding` if set, UTF-8 + otherwise. + +log.date:: + Default format for human-readable dates. (Compare the + `--date` option.) Defaults to "default", which means to write + dates like `Sat May 8 19:35:34 2010 -0500`. + +log.showroot:: + If `false`, 'git log' and related commands will not treat the + initial commit as a big creation event. Any root commits in + `git log -p` output would be shown without a diff attached. + The default is `true`. + +mailmap.file:: + See linkgit:git-shortlog[1]. + +notes.displayRef:: + Which refs, in addition to the default set by `core.notesRef` + or 'GIT_NOTES_REF', to read notes from when showing commit + messages with the 'log' family of commands. See + linkgit:git-notes[1]. ++ +May be an unabbreviated ref name or a glob and may be specified +multiple times. A warning will be issued for refs that do not exist, +but a glob that does not match any refs is silently ignored. ++ +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 ------ diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index e3d58cbac3..3ea5aad56c 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -40,16 +40,16 @@ OPTIONS -u:: The commit log message, author name and author email are taken from the e-mail, and after minimally decoding MIME - transfer encoding, re-coded in UTF-8 by transliterating + transfer encoding, re-coded in the charset specified by + i18n.commitencoding (defaulting to UTF-8) by transliterating them. This used to be optional but now it is the default. + Note that the patch is always used as-is without charset conversion, even with this flag. --encoding=<encoding>:: - Similar to -u but if the local convention is different - from what is specified by i18n.commitencoding, this flag - can be used to override it. + Similar to -u. But when re-coding, the charset specified here is + used instead of the one specified by i18n.commitencoding or UTF-8. -n:: Disable all charset re-coding of the metadata. diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index c2325ef90e..84043cc5b2 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -58,7 +58,12 @@ include::merge-options.txt[] -m <msg>:: Set the commit message to be used for the merge commit (in - case one is created). The 'git fmt-merge-msg' command can be + case one is created). + + If `--log` is specified, a shortlog of the commits being merged + will be appended to the specified message. + + The 'git fmt-merge-msg' command can be used to give a good default for automated 'git merge' invocations. diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 4e5113b837..5540af5d16 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -3,7 +3,7 @@ git-notes(1) NAME ---- -git-notes - Add/inspect object notes +git-notes - Add or inspect object notes SYNOPSIS -------- @@ -15,29 +15,31 @@ SYNOPSIS 'git notes' edit [<object>] 'git notes' show [<object>] 'git notes' remove [<object>] -'git notes' prune +'git notes' prune [-n | -v] DESCRIPTION ----------- -This command allows you to add/remove notes to/from objects, without -changing the objects themselves. +Adds, removes, or reads notes attached to objects, without touching +the objects themselves. -A typical use of notes is to extend a commit message without having -to change the commit itself. Such commit notes can be shown by `git log` -along with the original commit message. To discern these notes from the +By default, notes are saved to and read from `refs/notes/commits`, but +this default can be overridden. See the OPTIONS, CONFIGURATION, and +ENVIRONMENT sections below. If this ref does not exist, it will be +quietly created when it is first needed to store a note. + +A typical use of notes is to supplement a commit message without +changing the commit itself. Notes can be shown by 'git log' along with +the original commit message. To distinguish these notes from the message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes (<refname>):" (or -"Notes:" for the default setting). +"Notes:" for `refs/notes/commits`). -This command always manipulates the notes specified in "core.notesRef" -(see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF. -To change which notes are shown by 'git-log', see the -"notes.displayRef" configuration. +To change which notes are shown by 'git log', see the +"notes.displayRef" configuration in linkgit:git-log[1]. -See the description of "notes.rewrite.<command>" in -linkgit:git-config[1] for a way of carrying your notes across commands -that rewrite commits. +See the "notes.rewrite.<command>" configuration for a way to carry +notes across commands that rewrite commits. SUBCOMMANDS @@ -101,15 +103,20 @@ OPTIONS Use the given note message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. + Lines starting with `#` and empty lines other than a + single line between paragraphs will be stripped out. -F <file>:: --file=<file>:: Take the note message from the given file. Use '-' to read the note message from the standard input. + Lines starting with `#` and empty lines other than a + single line between paragraphs will be stripped out. -C <object>:: --reuse-message=<object>:: - Reuse the note message from the given note object. + Take the note message from the given blob object (for + example, another note). -c <object>:: --reedit-message=<object>:: @@ -117,22 +124,151 @@ OPTIONS the user can further edit the note message. --ref <ref>:: - Manipulate the notes tree in <ref>. This overrides both - GIT_NOTES_REF and the "core.notesRef" configuration. The ref + Manipulate the notes tree in <ref>. This overrides + 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref is taken to be in `refs/notes/` if it is not qualified. +-n:: + Do not remove anything; just report the object names whose notes + would be removed. + +-v:: + Report all object names whose notes are removed. + + +DISCUSSION +---------- -NOTES ------ +Commit notes are blobs containing extra information about an object +(usually information to supplement a commit's message). These blobs +are taken from notes refs. A notes ref is usually a branch which +contains "files" whose paths are the object names for the objects +they describe, with some directory separators included for performance +reasons footnote:[Permitted pathnames have the form +'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory +names of two hexadecimal digits each followed by a filename with the +rest of the object ID.]. Every notes change creates a new commit at the specified notes ref. You can therefore inspect the history of the notes by invoking, e.g., -`git log -p notes/commits`. +`git log -p notes/commits`. Currently the commit message only records +which operation triggered the update, and the commit authorship is +determined according to the usual rules (see linkgit:git-commit[1]). +These details may change in the future. + +It is also permitted for a notes ref to point directly to a tree +object, in which case the history of the notes can be read with +`git log -p -g <refname>`. + + +EXAMPLES +-------- + +You can use notes to add annotations with information that was not +available at the time a commit was written. + +------------ +$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 +$ git show -s 72a144e +[...] + Signed-off-by: Junio C Hamano <gitster@pobox.com> + +Notes: + Tested-by: Johannes Sixt <j6t@kdbg.org> +------------ + +In principle, a note is a regular Git blob, and any kind of +(non-)format is accepted. You can binary-safely create notes from +arbitrary files using 'git hash-object': + +------------ +$ cc *.c +$ blob=$(git hash-object -w a.out) +$ git notes --ref=built add -C "$blob" HEAD +------------ + +Of course, it doesn't make much sense to display non-text-format notes +with 'git log', so if you use such notes, you'll probably need to write +some special-purpose tools to do something useful with them. + + +CONFIGURATION +------------- -Currently the commit message only records which operation triggered -the update, and the commit authorship is determined according to the -usual rules (see linkgit:git-commit[1]). These details may change in -the future. +core.notesRef:: + Notes ref to read and manipulate instead of + `refs/notes/commits`. Must be an unabbreviated ref name. + This setting can be overridden through the environment and + command line. + +notes.displayRef:: + Which ref (or refs, if a glob or specified more than once), in + addition to the default set by `core.notesRef` or + 'GIT_NOTES_REF', to read notes from when showing commit + messages with the 'git log' family of commands. + This setting can be overridden on the command line or by the + 'GIT_NOTES_DISPLAY_REF' environment variable. + See linkgit:git-log[1]. + +notes.rewrite.<command>:: + When rewriting commits with <command> (currently `amend` or + `rebase`), if this variable is `false`, git will not copy + notes from the original to the rewritten commit. Defaults to + `true`. See also "`notes.rewriteRef`" below. ++ +This setting can be overridden by the 'GIT_NOTES_REWRITE_REF' +environment variable. + +notes.rewriteMode:: + When copying notes during a rewrite, what to do if the target + commit already has a note. Must be one of `overwrite`, + `concatenate`, and `ignore`. Defaults to `concatenate`. ++ +This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` +environment variable. + +notes.rewriteRef:: + When copying notes during a rewrite, specifies the (fully + qualified) ref whose notes should be copied. May be a glob, + in which case notes in all matching refs will be copied. You + may also specify this configuration several times. ++ +Does not have a default value; you must configure this variable to +enable note rewriting. ++ +Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. + + +ENVIRONMENT +----------- + +'GIT_NOTES_REF':: + Which ref to manipulate notes from, instead of `refs/notes/commits`. + This overrides the `core.notesRef` setting. + +'GIT_NOTES_DISPLAY_REF':: + Colon-delimited list of refs or globs indicating which refs, + in addition to the default from `core.notesRef` or + 'GIT_NOTES_REF', to read notes from when showing commit + messages. + This overrides the `notes.displayRef` setting. ++ +A warning will be issued for refs that do not exist, but a glob that +does not match any refs is silently ignored. + +'GIT_NOTES_REWRITE_MODE':: + When copying notes during a rewrite, what to do if the target + commit already has a note. + Must be one of `overwrite`, `concatenate`, and `ignore`. + This overrides the `core.rewriteMode` setting. + +'GIT_NOTES_REWRITE_REF':: + When rewriting commits, which notes to copy from the original + to the rewritten commit. Must be a colon-delimited list of + refs or globs. ++ +If not set in the environment, the list of notes to copy depends +on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. Author diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 0d07b1b207..50ba2e469f 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -206,6 +206,10 @@ OPTIONS --onto option is not specified, the starting point is <upstream>. May be any valid commit, and not just an existing branch name. ++ +As a special case, you may use "A...B" as a shortcut for the +merge base of A and B if there is exactly one merge base. You can +leave out at most one of A and B, in which case it defaults to HEAD. <upstream>:: Upstream branch to compare against. May be any valid commit, @@ -295,6 +299,7 @@ link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). --ignore-date:: These flags are passed to 'git am' to easily change the dates of the rebased commits (see linkgit:git-am[1]). + Incompatible with the --interactive option. -i:: --interactive:: diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 3fc599c0c7..aa021b0cb8 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,10 +10,11 @@ SYNOPSIS -------- [verse] 'git remote' [-v | --verbose] -'git remote add' [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url> +'git remote add' [-t <branch>] [-m <master>] [-f] [--tags|--no-tags] [--mirror] <name> <url> 'git remote rename' <old> <new> 'git remote rm' <name> 'git remote set-head' <name> (-a | -d | <branch>) +'git remote set-branches' <name> [--add] <branch>... 'git remote set-url' [--push] <name> <newurl> [<oldurl>] 'git remote set-url --add' [--push] <name> <newurl> 'git remote set-url --delete' [--push] <name> <url> @@ -51,6 +52,12 @@ update remote-tracking branches <name>/<branch>. With `-f` option, `git fetch <name>` is run immediately after the remote information is set up. + +With `--tags` option, `git fetch <name>` imports every tag from the +remote repository. ++ +With `--no-tags` option, `git fetch <name>` does not import tags from +the remote repository. ++ With `-t <branch>` option, instead of the default glob refspec for the remote to track all branches under `$GIT_DIR/remotes/<name>/`, a refspec to track only `<branch>` @@ -104,6 +111,18 @@ remote set-head origin master" will set `$GIT_DIR/refs/remotes/origin/HEAD` to `refs/remotes/origin/master` already exists; if not it must be fetched first. + +'set-branches':: + +Changes the list of branches tracked by the named remote. +This can be used to track a subset of the available remote branches +after the initial setup for a remote. ++ +The named branches will be interpreted as if specified with the +`-t` option on the 'git remote add' command line. ++ +With `--add`, instead of replacing the list of currently tracked +branches, adds to that list. + 'set-url':: Changes URL remote points to. Sets first URL remote points to matching diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index ced35b2f53..12622fc49a 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -119,6 +119,13 @@ Sending value reverts to plain SMTP. Default is the value of 'sendemail.smtpencryption'. +--smtp-domain=<FQDN>:: + Specifies the Fully Qualified Domain Name (FQDN) used in the + HELO/EHLO command to the SMTP server. Some servers require the + FQDN to match your IP address. If not set, git send-email attempts + to determine your FQDN automatically. Default is the value of + 'sendemail.smtpdomain'. + --smtp-pass[=<password>]:: Password for SMTP-AUTH. The argument is optional: If no argument is specified, then the empty string is used as @@ -300,6 +307,21 @@ sendemail.confirm:: in the previous section for the meaning of these values. +Use gmail as the smtp server +---------------------------- + +Add the following section to the config file: + + [sendemail] + smtpencryption = tls + smtpserver = smtp.gmail.com + smtpuser = yourname@gmail.com + smtpserverport = 587 + +Note: the following perl modules are required + Net::SMTP::SSL, MIME::Base64 and Authen::SASL + + Author ------ Written by Ryan Anderson <ryan@michonline.com> diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index dfd4d0c223..bc1ac77495 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w] -'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] [<committish>...] +'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] <commit>... DESCRIPTION ----------- @@ -19,6 +19,11 @@ the first line of the commit message will be shown. Additionally, "[PATCH]" will be stripped from the commit description. +If no revisions are passed on the command line and either standard input +is not a terminal or there is no current branch, 'git shortlog' will +output a summary of the log read from standard input, without +reference to the current repository. + OPTIONS ------- @@ -39,6 +44,14 @@ OPTIONS --email:: Show the email address of each author. +--format[='<format>']:: + Instead of the commit subject, use some other information to + describe each commit. '<format>' can be any string accepted + by the `--format` option of 'git log', such as '{asterisk} [%h] %s'. + (See the "PRETTY FORMATS" section of linkgit:git-log[1].) + + Each pretty-printed commit will be rewrapped before it is shown. + -w[<width>[,<indent1>[,<indent2>]]]:: Linewrap the output by wrapping each line at `width`. The first line of each entry is indented by `indent1` spaces, and the second diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 2d4bbfcaf4..fd0fe7cb56 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -27,6 +27,10 @@ OPTIONS --short:: Give the output in the short-format. +-b:: +--branch:: + Show the branch and tracking info even in short-format. + --porcelain:: Give the output in a stable, easy-to-parse format for scripts. Currently this is identical to --short output, but is guaranteed @@ -120,6 +124,10 @@ Ignored files are not listed. ? ? untracked ------------------------------------------------- +If -b is used the short-format status is preceded by a line + +## branchname tracking info + There is an alternate -z format recommended for machine parsing. In that format, the status field is the same, but some other things change. First, the '->' is omitted from rename entries and the field @@ -128,7 +136,7 @@ order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL and the terminating newline (but a space still separates the status field from the first filename). Third, filenames containing special characters are not specially formatted; no quoting or -backslash-escaping is performed. +backslash-escaping is performed. Fourth, there is no branch line. CONFIGURATION ------------- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2502531a3d..cdabfd29ad 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -145,10 +145,12 @@ summary:: foreach:: Evaluates an arbitrary shell command in each checked out submodule. - The command has access to the variables $name, $path and $sha1: + The command has access to the variables $name, $path, $sha1 and + $toplevel: $name is the name of the relevant submodule section in .gitmodules, $path is the name of the submodule directory relative to the - superproject, and $sha1 is the commit as recorded in the superproject. + superproject, $sha1 is the commit as recorded in the superproject, + and $toplevel is the absolute path to the top-level of the superproject. Any submodules defined in the superproject but not checked out are ignored by this command. Unless given --quiet, foreach prints the name of each submodule before evaluating the command. diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 99f3c1ea6c..b09bd9761f 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -243,7 +243,7 @@ where <name> is the name of the SVN repository as specified by the -R option to --username;; Specify the SVN username to perform the commit as. This option overrides - configuration property 'username'. + the 'username' configuration property. --commit-url;; Use the specified URL to connect to the destination Subversion diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 68dc1879fe..765d4b312e 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -93,8 +93,6 @@ OPTIONS This option can be also used as a coarse file-level mechanism to ignore uncommitted changes in tracked files (akin to what `.gitignore` does for untracked files). -You should remember that an explicit 'git add' operation will -still cause the file to be refreshed from the working tree. Git will fail (gracefully) in case it needs to modify this file in the index e.g. when merging in a commit; thus, in case the assumed-untracked file is changed upstream, diff --git a/Documentation/git.txt b/Documentation/git.txt index c4024d0edd..bec6348dab 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path] [-p|--paginate|--no-pager] [--no-replace-objects] [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE] + [-c name=value] [--help] COMMAND [ARGS] DESCRIPTION @@ -228,6 +229,12 @@ displayed. See linkgit:git-help[1] for more information, because `git --help ...` is converted internally into `git help ...`. +-c <name>=<value>:: + Pass a configuration parameter to the command. The value + given will override values from configuration files. + The <name> is expected in the same format as listed by + 'git config' (subkeys separated by dots). + --exec-path:: Path to wherever your core git programs are installed. This can also be controlled by setting the GIT_EXEC_PATH @@ -538,6 +545,16 @@ git so take care if using Cogito etc. a GIT_DIR set on the command line or in the environment. (Useful for excluding slow-loading network directories.) +'GIT_DISCOVERY_ACROSS_FILESYSTEM':: + When run in a directory that does not have ".git" repository + directory, git tries to find such a directory in the parent + directories to find the top of the working tree, but by default it + does not cross filesystem boundaries. This environment variable + can be set to true to tell git not to stop at filesystem + boundaries. Like 'GIT_CEILING_DIRECTORIES', this will not affect + an explicit repository directory set via 'GIT_DIR' or on the + command line. + git Commits ~~~~~~~~~~~ 'GIT_AUTHOR_NAME':: diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index d892e642ed..0523a57698 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -360,7 +360,7 @@ patterns are available: Customizing word diff ^^^^^^^^^^^^^^^^^^^^^ -You can customize the rules that `git diff --color-words` uses to +You can customize the rules that `git diff --word-diff` uses to split words in a line, by specifying an appropriate regular expression in the "diff.*.wordRegex" configuration variable. For example, in TeX a backslash followed by a sequence of letters forms a command, but @@ -414,6 +414,26 @@ because it quickly conveys the changes you have made), you should generate it separately and send it as a comment _in addition to_ the usual binary diff that you might send. +Because text conversion can be slow, especially when doing a +large number of them with `git log -p`, git provides a mechanism +to cache the output and use it in future diffs. To enable +caching, set the "cachetextconv" variable in your diff driver's +config. For example: + +------------------------ +[diff "jpg"] + textconv = exif + cachetextconv = true +------------------------ + +This will cache the result of running "exif" on each blob +indefinitely. If you change the textconv config variable for a +diff driver, git will automatically invalidate the cache entries +and re-run the textconv filter. If you want to invalidate the +cache manually (e.g., because your version of "exif" was updated +and now produces better output), you can remove the cache +manually with `git update-ref -d refs/notes/textconv/jpg` (where +"jpg" is the name of the diff driver, as in the example above). Performing a three-way merge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt index 9de8caf5d1..5d91a7e5b3 100644 --- a/Documentation/gitdiffcore.txt +++ b/Documentation/gitdiffcore.txt @@ -227,8 +227,8 @@ 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 "original" side has the specified string and -whose "result" side does not. Such a filepair represents "the +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 opposite case that loses the specified string. diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 98c459dc82..e10fa88b8c 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -83,16 +83,20 @@ Patterns have the following format: - If the pattern does not contain a slash '/', git treats it as a shell glob pattern and checks for a match against the - pathname without leading directories. + pathname relative to the location of the `.gitignore` file + (relative to the toplevel of the work tree if not from a + `.gitignore` file). - Otherwise, git treats the pattern as a shell glob suitable for consumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the pattern will not match a / in the pathname. For example, "Documentation/\*.html" matches - "Documentation/git.html" but not - "Documentation/ppc/ppc.html". A leading slash matches the - beginning of the pathname; for example, "/*.c" matches - "cat-file.c" but not "mozilla-sha1/sha1.c". + "Documentation/git.html" but not "Documentation/ppc/ppc.html" + or "tools/perf/Documentation/perf.html". + + - A leading slash matches the beginning of the pathname. + For example, "/*.c" matches "cat-file.c" but not + "mozilla-sha1/sha1.c". An example: diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 1686a54d22..8c68ce94f9 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -11,7 +11,12 @@ have limited your view of history: for example, if you are only interested in changes related to a certain directory or file. -Here are some additional details for each format: +There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +'format:' string, as described below (see +linkgit:git-config[1]). Here are the details of the +built-in formats: * 'oneline' @@ -76,9 +81,9 @@ displayed in full, regardless of whether --abbrev or true parent commits, without taking grafts nor history simplification into account. -* 'format:' +* 'format:<string>' + -The 'format:' format allows you to specify which information +The 'format:<string>' format allows you to specify which information you want to show. It works a little bit like printf format, with the notable exception that you get a newline with '%n' instead of '\n'. @@ -123,6 +128,7 @@ The placeholders are: - '%s': subject - '%f': sanitized subject line, suitable for a filename - '%b': body +- '%B': raw body (unwrapped subject and body) - '%N': commit notes - '%gD': reflog selector, e.g., `refs/stash@\{1\}` - '%gd': shortened reflog selector, e.g., `stash@\{1\}` diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index af6d2b995a..d78e121c76 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -3,8 +3,9 @@ Pretty-print the contents of the commit logs in a given format, where '<format>' can be one of 'oneline', 'short', 'medium', - 'full', 'fuller', 'email', 'raw' and 'format:<string>'. - When omitted, the format defaults to 'medium'. + 'full', 'fuller', 'email', 'raw' and 'format:<string>'. See + the "PRETTY FORMATS" section for some additional details for each + format. When omitted, the format defaults to 'medium'. + Note: you can specify the default pretty format in the repository configuration (see linkgit:git-config[1]). |