diff options
Diffstat (limited to 'Documentation')
25 files changed, 620 insertions, 123 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..2eef0380ea --- /dev/null +++ b/Documentation/RelNotes-1.7.1.1.txt @@ -0,0 +1,46 @@ +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. + + * "git am -3" did not show diagnosis when the patch in the message was corrupt. + + * "git bundle --stdin" segfaulted. + + * "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 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 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 index 37781b4f14..1df22be126 100644 --- a/Documentation/RelNotes-1.7.2.txt +++ b/Documentation/RelNotes-1.7.2.txt @@ -4,37 +4,104 @@ 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. + * 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 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 send-email" learned --smtp-domain option to specify the domainname - used in the EHLO/HELO exchange. + * "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 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. + + * "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 log --follow <path>" follows across copies (it used to only follow + renames). This may make the processing more expensive. + + * "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 revert" learned --strategy option to specify the merge strategy. - * 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. + * "git status [-s] --ignored" can be used to list ignored paths. - * 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. + * Various "gitweb" enhancements and clean-ups, including syntax + highlighting. Fixes since v1.7.1 ------------------ - * In 1.7.1, "git status" stopped refreshing the index by mistake. - All of the fixes in v1.7.1.X maintenance series are included in this release, unless otherwise noted. + * We didn't recognize timezone "Z" as a synonym for "UTC" (75b37e70). + + * "git checkout" and "git rebase" overwrote paths that are marked "assume + unchanged" (aecda37c). + + * "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" 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 (582aa00). + + * "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 (29609e68). + + * "git reset --hard" started from a wrong directory and a working tree in + a nonstandard location is in use got confused (560fb6a1). + -- exec >/var/tmp/1 -O=v1.7.1-77-gb751157 +O=v1.7.1-336-g0925c02 echo O=$(git describe master) git shortlog --no-merges master ^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 39140bad4d..95cf73cd47 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -520,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 @@ -946,13 +940,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 @@ -1475,6 +1475,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. @@ -1587,7 +1597,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 @@ -1691,6 +1703,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 4a968591cb..e745a3ccdc 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -127,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 @@ -143,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:: @@ -178,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..afda5c36b5 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -9,7 +9,7 @@ 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>...] @@ -90,6 +90,24 @@ 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 branch named <new_branch>, unparented to any other + branch. The new branch you switch to does not have any commit + and after the first one it will become the root of a new history + completely unconnected from all the other branches. ++ +When you use "--orphan", the index and the working tree are kept intact. +This allows you to start a new history that records set of paths similar +to that of the start-point commit, which is useful when you want to keep +different branches for different audiences you are working to like when +you have an open source and commercial versions of a software, for example. ++ +If you want to start a disconnected history that records set of paths +totally different from the original branch, you may want to first clear +the index and the working tree, by running "git rm -rf ." from the +top-level of the working tree, before preparing your files (by copying +from elsewhere, extracting a tarball, etc.) in the working tree. + -m:: --merge:: When switching branches, @@ -136,6 +154,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 32c482f33f..c28603ecf5 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -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. 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-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-log.txt b/Documentation/git-log.txt index 57aa574675..0e6ff31823 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -57,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 @@ -133,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 5863decdc9..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, diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index de4386bf7e..aa021b0cb8 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] [--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>) @@ -52,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>` 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-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-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 a8500d1772..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 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 bd760d3bd1..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'. 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]). |