diff options
Diffstat (limited to 'Documentation')
51 files changed, 1130 insertions, 229 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 8a8a395..04f69cf 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -264,7 +264,9 @@ manpage-base-url.xsl: manpage-base-url.xsl.in mv $@+ $@ user-manual.xml: user-manual.txt user-manual.conf - $(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book $< + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d book -o $@+ $< && \ + mv $@+ $@ technical/api-index.txt: technical/api-index-skel.txt \ technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) @@ -278,7 +280,9 @@ XSLT = docbook.xsl XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css user-manual.html: user-manual.xml - $(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@ $(XSLT) $< + $(QUIET_XSLTPROC)$(RM) $@+ $@ && \ + xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \ + mv $@+ $@ git.info: user-manual.texi $(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi diff --git a/Documentation/RelNotes-1.7.0.6.txt b/Documentation/RelNotes-1.7.0.6.txt new file mode 100644 index 0000000..b2852b6 --- /dev/null +++ b/Documentation/RelNotes-1.7.0.6.txt @@ -0,0 +1,13 @@ +Git v1.7.0.6 Release Notes +========================== + +Fixes since v1.7.0.5 +-------------------- + + * "git diff --stat" used "int" to count the size of differences, + which could result in overflowing. + + * "git rev-list --abbrev-commit" defaulted to 40-byte abbreviations, unlike + newer tools in the git toolset. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes-1.7.1.txt b/Documentation/RelNotes-1.7.1.txt new file mode 100644 index 0000000..9d89fed --- /dev/null +++ b/Documentation/RelNotes-1.7.1.txt @@ -0,0 +1,89 @@ +Git v1.7.1 Release Notes +======================== + +Updates since v1.7.0 +-------------------- + + * Eric Raymond is the maintainer of updated CIAbot scripts, in contrib/. + + * gitk updates. + + * Some commands (e.g. svn and http interfaces) that interactively ask + for a password can be told to use an external program given via + GIT_ASKPASS. + + * Conflict markers that lead the common ancestor in diff3-style output + now have a label, which hopefully would help third-party tools that + expect one. + + * Comes with an updated bash-completion script. + + * "git am" learned "--keep-cr" option to handle inputs that are + a mixture of changes to files with and without CRLF line endings. + + * "git cvsimport" learned -R option to leave revision mapping between + CVS revisions and resulting git commits. + + * "git diff --submodule" notices and describes dirty submodules. + + * "git for-each-ref" learned %(symref), %(symref:short) and %(flag) + tokens. + + * "git hash-object --stdin-paths" can take "--no-filters" option now. + + * "git init" can be told to look at init.templatedir configuration + variable (obviously that has to come from either /etc/gitconfig or + $HOME/.gitconfig). + + * "git grep" learned "--no-index" option, to search inside contents that + are not managed by git. + + * "git grep" learned --color=auto/always/never. + + * "git grep" learned to paint filename and line-number in colors. + + * "git log -p --first-parent -m" shows one-parent diff for merge + commits, instead of showing combined diff. + + * "git merge-file" learned to use custom conflict marker size and also + to use the "union merge" behaviour. + + * "git notes" command has been rewritten in C and learned many commands + and features to help you carry notes forward across rebases and amends. + + * "git request-pull" identifies the commit the request is relative to in + a more readable way. + + * "git reset" learned "--keep" option that lets you discard commits + near the tip while preserving your local changes in a way similar + to how "git checkout branch" does. + + * "git status" notices and describes dirty submodules. + + * "git svn" should work better when interacting with repositories + with CRLF line endings. + + * "git imap-send" learned to support CRAM-MD5 authentication. + + * "gitweb" installation procedure can use "minified" js/css files + better. + + * Various documentation updates. + +Fixes since v1.7.0 +------------------ + +All of the fixes in v1.7.0.X maintenance series are included in this +release, unless otherwise noted. + + * "git add frotz/nitfol" did not complain when the entire frotz/ directory + was ignored. + + * "git diff --stat" used "int" to count the size of differences, + which could result in overflowing. + + * "git rev-list --pretty=oneline" didn't terminate a record with LF for + commits without any message. + + * "git rev-list --abbrev-commit" defaulted to 40-byte abbreviations, unlike + newer tools in the git toolset. diff --git a/Documentation/RelNotes-1.7.2.txt b/Documentation/RelNotes-1.7.2.txt new file mode 100644 index 0000000..37781b4 --- /dev/null +++ b/Documentation/RelNotes-1.7.2.txt @@ -0,0 +1,40 @@ +Git v1.7.2 Release Notes (draft) +================================ + +Updates since v1.7.1 +-------------------- + + * 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. + + * 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 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. + + * 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. + + +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. + +-- +exec >/var/tmp/1 +O=v1.7.1-77-gb751157 +echo O=$(git describe master) +git shortlog --no-merges master ^maint ^$O diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c686f86..8db22ef 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -53,6 +53,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 +198,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 @@ -520,11 +547,9 @@ 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 -the emails through that. Just make sure to disable line wrapping in that -email client. Alternatively, use "git send-email" instead. +the emails through that. -Submitting properly formatted patches via Gmail is simple now that -IMAP support is available. First, edit your ~/.gitconfig to specify your +To submit using the IMAP interface, first, edit your ~/.gitconfig to specify your account settings: [imap] @@ -538,14 +563,29 @@ account settings: You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error that the "Folder doesn't exist". -Next, ensure that your Gmail settings are correct. In "Settings" the -"Use Unicode (UTF-8) encoding for outgoing messages" should be checked. +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. + + $ git format-patch --cover-letter -M --stdout origin/master | git imap-send -Once your commits are ready to send to the mailing list, run the following -command to send the patch emails to your Gmail Drafts folder. +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: - $ git format-patch -M --stdout origin/master | git imap-send +[sendemail] + smtpencryption = tls + smtpserver = smtp.gmail.com + smtpuser = user@gmail.com + smtppass = p4ssw0rd + smtpserverport = 587 -Go to your Gmail account, open the Drafts folder, find the patch email, fill -in the To: and CC: fields and send away! +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/config.txt b/Documentation/config.txt index 75b8afe..87f397e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -198,11 +198,11 @@ core.quotepath:: core.autocrlf:: If true, makes git convert `CRLF` at the end of lines in text files to - `LF` when reading from the filesystem, and convert in reverse when - writing to the filesystem. The variable can be set to + `LF` when reading from the work tree, and convert in reverse when + writing to the work tree. The variable can be set to 'input', in which case the conversion happens only while - reading from the filesystem but files are written out with - `LF` at the end of lines. A file is considered + reading from the work tree but files are written out to the work + tree with `LF` at the end of lines. A file is considered "text" (i.e. be subjected to the autocrlf mechanism) based on the file's `crlf` attribute, or if `crlf` is unspecified, based on the file's contents. See linkgit:gitattributes[5]. @@ -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 @@ -519,10 +521,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. + after the full SHA-1 of the commit they annotate. The ref + must be fully qualified. + If such a file exists in the given ref, the referenced blob is read, and -appended to the commit message, separated by a "Notes:" line. If the +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. + @@ -555,6 +559,13 @@ it will be treated as a shell command. For example, defining executed from the top-level directory of a repository, which may not necessarily be the current directory. +am.keepcr:: + If true, git-am will call git-mailsplit for patches in mbox format + with parameter '--keep-cr'. In this case git-mailsplit will + not remove `\r` from lines ending with `\r\n`. Can be overrriden + by giving '--no-keep-cr' from the command line. + See linkgit:git-am[1], linkgit:git-mailsplit[1]. + apply.ignorewhitespace:: When set to 'change', tells 'git apply' to ignore changes in whitespace, in the same way as the '--ignore-space-change' @@ -683,9 +694,29 @@ color.grep:: `never`), never. When set to `true` or `auto`, use color only when the output is written to the terminal. Defaults to `false`. -color.grep.match:: - Use customized color for matches. The value of this variable - may be specified as in color.branch.<slot>. +color.grep.<slot>:: + Use customized color for grep colorization. `<slot>` specifies which + part of the line to use the specified color, and is one of ++ +-- +`context`;; + non-matching text in context lines (when using `-A`, `-B`, or `-C`) +`filename`;; + filename prefix (when not using `-h`) +`function`;; + function name lines (when using `-p`) +`linenumber`;; + line number prefix (when using `-n`) +`match`;; + matching text +`selected`;; + non-matching text in selected lines +`separator`;; + separators between fields on a line (`:`, `-`, and `=`) + and between hunks (`--`) +-- ++ +The values of these variables may be specified as in color.branch.<slot>. color.interactive:: When set to `always`, always use colors for interactive prompts @@ -915,13 +946,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 @@ -1203,6 +1240,10 @@ imap:: The configuration variables in the 'imap' section are described in linkgit:git-imap-send[1]. +init.templatedir:: + Specify the directory from which templates will be copied. + (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) + instaweb.browser:: Specify the program that will be used to browse your working repository in gitweb. See linkgit:git-instaweb[1]. @@ -1235,6 +1276,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. @@ -1303,6 +1351,53 @@ mergetool.keepTemporaries:: mergetool.prompt:: Prompt before each invocation of the merge resolution program. +notes.displayRef:: + The (fully qualified) refname from which to show notes when + showing commit messages. The value of this variable can be set + to a glob, in which case notes from all matching refs will be + shown. You may also specify this configuration variable + several 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 overridden with the `GIT_NOTES_DISPLAY_REF` +environment variable, which must be a colon separated list of refs or +globs. ++ +The effective value of "core.notesRef" (possibly overridden by +GIT_NOTES_REF) is also implicitly added to the list of refs to be +displayed. + +notes.rewrite.<command>:: + When rewriting commits with <command> (currently `amend` or + `rebase`) and this variable is set to `true`, git + automatically copies your notes from the original to the + rewritten commit. Defaults to `true`, but see + "notes.rewriteRef" below. + +notes.rewriteMode:: + When copying notes during a rewrite (see the + "notes.rewrite.<command>" option), determines what to do if + the target commit already has a note. Must be one of + `overwrite`, `concatenate`, or `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. The ref 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. ++ +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 window size is given on the command line. Defaults to 10. @@ -1436,7 +1531,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", @@ -1498,7 +1593,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 @@ -1562,6 +1659,7 @@ sendemail.smtppass:: sendemail.suppresscc:: sendemail.suppressfrom:: sendemail.to:: +sendemail.smtpdomain:: sendemail.smtpserver:: sendemail.smtpserverport:: sendemail.smtpuser:: diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 0f25ba7..8f9a241 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -56,7 +56,8 @@ combined diff format "git-diff-tree", "git-diff-files" and "git-diff" can take '-c' or '--cc' option to produce 'combined diff'. For showing a merge commit -with "git log -p", this is the default format. +with "git log -p", this is the default format; you can force showing +full diff with the '-m' option. A 'combined diff' format looks like this: ------------ diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 8707d0e..0d89aaa 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[] @@ -94,8 +95,8 @@ Also, when `--raw` or `--numstat` has been given, do not munge pathnames and use NULs as output field terminators. endif::git-log[] ifndef::git-log[] - When `--raw` or `--numstat` has been given, do not munge - pathnames and use NULs as output field terminators. + When `--raw`, `--numstat`, `--name-only` or `--name-status` has been + given, do not munge pathnames and use NULs as output field terminators. endif::git-log[] + Without this option, each pathname output will have TAB, LF, double quotes, @@ -117,18 +118,48 @@ any of those replacements occurred. option and lists the commits in that commit range like the 'summary' option of linkgit:git-submodule[1] does. ---color:: +--color[=<when>]:: Show colored diff. + The value must be always (the default), never, or auto. --no-color:: Turn off colored diff, even when the configuration file 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. +-- ++ +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. + -When a <regex> is specified, every non-overlapping match of the +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 @@ -140,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:: diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index 9310b65..e0ba8cc 100644 --- a/Documentation/everyday.txt +++ b/Documentation/everyday.txt @@ -1,13 +1,8 @@ Everyday GIT With 20 Commands Or So =================================== -<<Basic Repository>> commands are needed by people who have a -repository --- that is everybody, because every working tree of -git is a repository. - -In addition, <<Individual Developer (Standalone)>> commands are -essential for anybody who makes a commit, even for somebody who -works alone. +<<Individual Developer (Standalone)>> commands are essential for +anybody who makes a commit, even for somebody who works alone. If you work with other people, you will need commands listed in the <<Individual Developer (Participant)>> section as well. @@ -20,46 +15,6 @@ administrators who are responsible for the care and feeding of git repositories. -Basic Repository[[Basic Repository]] ------------------------------------- - -Everybody uses these commands to maintain git repositories. - - * linkgit:git-init[1] or linkgit:git-clone[1] to create a - new repository. - - * linkgit:git-fsck[1] to check the repository for errors. - - * linkgit:git-gc[1] to do common housekeeping tasks such as - repack and prune. - -Examples -~~~~~~~~ - -Check health and remove cruft.:: -+ ------------- -$ git fsck <1> -$ git count-objects <2> -$ git gc <3> ------------- -+ -<1> running without `\--full` is usually cheap and assures the -repository health reasonably well. -<2> check how many loose objects there are and how much -disk space is wasted by not repacking. -<3> repacks the local repository and performs other housekeeping tasks. - -Repack a small project into single pack.:: -+ ------------- -$ git gc <1> ------------- -+ -<1> pack all the objects reachable from the refs into one pack, -then remove the other packs. - - Individual Developer (Standalone)[[Individual Developer (Standalone)]] ---------------------------------------------------------------------- @@ -67,6 +22,8 @@ A standalone individual developer does not exchange patches with other people, and works alone in a single repository, using the following commands. + * linkgit:git-init[1] to create a new repository. + * linkgit:git-show-branch[1] to see where you are. * linkgit:git-log[1] to see what happened. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index fe716b2..044ec88 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -78,9 +78,16 @@ ifndef::git-pull[] -q:: --quiet:: Pass --quiet to git-fetch-pack and silence any other internally - used git commands. + used git commands. Progress is not reported to the standard error + stream. -v:: --verbose:: Be verbose. endif::git-pull[] + +--progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless -q + is specified. This flag forces progress status even if the + standard error stream is not directed to a terminal. diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 23864df..9e62f87 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -9,7 +9,7 @@ git-am - Apply a series of patches from a mailbox SYNOPSIS -------- [verse] -'git am' [--signoff] [--keep] [--utf8 | --no-utf8] +'git am' [--signoff] [--keep] [--keep-cr | --no-keep-cr] [--utf8 | --no-utf8] [--3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] @@ -39,6 +39,13 @@ OPTIONS --keep:: Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). +--keep-cr:: +--no-keep-cr:: + With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) + with the same option, to prevent it from stripping CR at the end of + lines. `am.keepcr` configuration variable can be used to specify the + default behaviour. `--no-keep-cr` is useful to override `am.keepcr`. + -c:: --scissors:: Remove everything in body before a scissors line (see diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 60fa684..1940256 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,7 +8,7 @@ git-branch - List, create, or delete branches SYNOPSIS -------- [verse] -'git branch' [--color | --no-color] [-r | -a] +'git branch' [--color[=<when>] | --no-color] [-r | -a] [-v [--abbrev=<length> | --no-abbrev]] [(--merged | --no-merged | --contains) [<commit>]] 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] @@ -88,12 +88,14 @@ OPTIONS -M:: Move/rename a branch even if the new branch name already exists. ---color:: +--color[=<when>]:: Color branches to highlight current, local, and remote branches. + The value must be always (the default), never, or auto. --no-color:: Turn off branch colors, even when the configuration file gives the default to color output. + Same as `--color=never`. -r:: List or delete (if used with -d) the remote-tracking branches. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 37c1810..4505eb6 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, diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 78f4714..d71607a 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -7,7 +7,7 @@ git-cherry-pick - Apply the change introduced by an existing commit SYNOPSIS -------- -'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] <commit> +'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit> DESCRIPTION ----------- @@ -70,6 +70,10 @@ effect to your index in a row. --signoff:: Add Signed-off-by line at the end of the commit message. +--ff:: + If the current HEAD is the same as the parent of the + cherry-pick'ed commit, then a fast forward to this commit will + be performed. Author ------ diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index d15cb17..dc7d3d1 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -102,7 +102,8 @@ objects from the source repository into a pack in the cloned repository. --verbose:: -v:: - Run verbosely. + Run verbosely. Does not affect the reporting of progress status + to the standard error stream. --progress:: Progress status is reported on the standard error stream @@ -149,8 +150,7 @@ objects from the source repository into a pack in the cloned repository. --template=<template_directory>:: Specify the directory from which templates will be used; - if unset the templates are taken from the installation - defined default, typically `/usr/share/git-core/templates`. + (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) --depth <depth>:: Create a 'shallow' clone with a history truncated to the diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 64fb458..32c482f 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>...] @@ -131,6 +131,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-cvsimport.txt b/Documentation/git-cvsimport.txt index ddfcb3d..8bcd875 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -13,7 +13,7 @@ SYNOPSIS [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] - [-r <remote>] [<CVS_module>] + [-r <remote>] [-R] [<CVS_module>] DESCRIPTION @@ -157,6 +157,22 @@ It is not recommended to use this feature if you intend to export changes back to CVS again later with 'git cvsexportcommit'. +-R:: + Generate a `$GIT_DIR/cvs-revisions` file containing a mapping from CVS + revision numbers to newly-created Git commit IDs. The generated file + will contain one line for each (filename, revision) pair imported; + each line will look like ++ +--------- +src/widget.c 1.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7 +--------- ++ +The revision data is appended to the file if it already exists, for use when +doing incremental imports. ++ +This option may be useful if you have CVS revision numbers stored in commit +messages, bug-tracking systems, email archives, and the like. + -h:: Print a short usage message and exit. diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 7e83288..390d85c 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-format-patch.txt b/Documentation/git-format-patch.txt index 9674f9d..835fb71 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -18,7 +18,7 @@ SYNOPSIS [--in-reply-to=Message-Id] [--suffix=.<sfx>] [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] - [--cc=<email>] + [--to=<email>] [--cc=<email>] [--cover-letter] [<common diff options>] [ <since> | <revision range> ] @@ -162,6 +162,10 @@ will want to ensure that threading is disabled for `git send-email`. allows for useful naming of a patch series, and can be combined with the `--numbered` option. +--to=<email>:: + Add a `To:` header to the email headers. This is in addition + to any configured headers, and may be used multiple times. + --cc=<email>:: Add a `Cc:` header to the email headers. This is in addition to any configured headers, and may be used multiple times. @@ -202,8 +206,8 @@ CONFIGURATION ------------- You can specify extra mail header lines to be added to each message, defaults for the subject prefix and file suffix, number patches when -outputting more than one patch, add "Cc:" headers, configure attachments, -and sign off patches with configuration variables. +outputting more than one patch, add "To" or "Cc:" headers, configure +attachments, and sign off patches with configuration variables. ------------ [format] @@ -211,6 +215,7 @@ and sign off patches with configuration variables. subjectprefix = CHANGE suffix = .txt numbered = auto + to = <email> cc = <email> attach [ = mime-boundary-string ] signoff = true diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 189573a..a9e0882 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-grep.txt b/Documentation/git-grep.txt index ee506e6..4b32322 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -17,7 +17,7 @@ SYNOPSIS [-z | --null] [-c | --count] [--all-match] [-q | --quiet] [--max-depth <depth>] - [--color | --no-color] + [--color[=<when>] | --no-color] [-A <post-context>] [-B <pre-context>] [-C <context>] [-f <file>] [-e] <pattern> [--and|--or|--not|(|)|-e <pattern>...] @@ -114,12 +114,14 @@ OPTIONS Instead of showing every matched line, show the number of lines that match. ---color:: +--color[=<when>]:: Show colored matches. + The value must be always (the default), never, or auto. --no-color:: Turn off match highlighting, even when the configuration file gives the default to color output. + Same as `--color=never`. -[ABC] <context>:: Show `context` trailing (`A` -- after), or leading (`B` diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 479fce4..6904739 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin] [--] <file>... -'git hash-object' [-t <type>] [-w] --stdin-paths < <list-of-paths> +'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters] < <list-of-paths> DESCRIPTION ----------- diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index ad446b0..57aba42 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -73,6 +73,10 @@ imap.preformattedHTML:: option causes Thunderbird to send the patch as a plain/text, format=fixed email. Default is `false`. +imap.authMethod:: + Specify authenticate method for authentication with IMAP server. + Current supported method is 'CRAM-MD5' only. + Examples ~~~~~~~~ diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 7ee102d..246b07e 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -28,14 +28,8 @@ current working directory. --template=<template_directory>:: -Provide the directory from which templates will be used. The default template -directory is `/usr/share/git-core/templates`. - -When specified, `<template_directory>` is used as the source of the template -files rather than the default. The template files include some directory -structure, some suggested "exclude patterns", and copies of non-executing -"hook" files. The suggested patterns and hook files are all modifiable and -extensible. +Specify the directory from which templates will be used. (See the "TEMPLATE +DIRECTORY" section below.) --shared[={false|true|umask|group|all|world|everybody|0xxx}]:: @@ -106,6 +100,25 @@ of the repository, such as installing the default hooks and setting the configuration variables. The old name is retained for backward compatibility reasons. +TEMPLATE DIRECTORY +------------------ + +The template directory contains files and directories that will be copied to +the `$GIT_DIR` after it is created. + +The template directory used will (in order): + + - The argument given with the `--template` option. + + - The contents of the `$GIT_TEMPLATE_DIR` environment variable. + + - The `init.templatedir` configuration variable. + + - The default template directory: `/usr/share/git-core/templates`. + +The default template directory includes some directory structure, some +suggested "exclude patterns", and copies of sample "hook" files. +The suggested patterns and hook files are all modifiable and extensible. EXAMPLES -------- diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 0e39bb6..57aa574 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 @@ -118,6 +119,15 @@ git log master --not --remotes=*/master:: Shows all commits that are in local master but not in any remote repository master branches. +git log -p -m --first-parent:: + + Shows the history including change diffs, but only from the + "main branch" perspective, skipping commits that come from merged + branches, and showing full diffs of changes introduced by the merges. + This makes sense only when following a strict policy of merging all + topic branches when staying on a single integration branch. + + Discussion ---------- diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index 5cc94ec..a634485 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -7,7 +7,7 @@ git-mailsplit - Simple UNIX mbox splitter program SYNOPSIS -------- -'git mailsplit' [-b] [-f<nn>] [-d<prec>] -o<directory> [--] [<mbox>|<Maildir>...] +'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [<mbox>|<Maildir>...] DESCRIPTION ----------- @@ -43,6 +43,9 @@ OPTIONS Skip the first <nn> numbers, for example if -f3 is specified, start the numbering with 0004. +--keep-cr:: + Do not remove `\r` from lines ending with `\r\n`. + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-merge-file.txt b/Documentation/git-merge-file.txt index 234269a..f334d69 100644 --- a/Documentation/git-merge-file.txt +++ b/Documentation/git-merge-file.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git merge-file' [-L <current-name> [-L <base-name> [-L <other-name>]]] - [--ours|--theirs] [-p|--stdout] [-q|--quiet] + [--ours|--theirs|--union] [-p|--stdout] [-q|--quiet] [--marker-size=<n>] <current-file> <base-file> <other-file> @@ -35,9 +35,10 @@ normally outputs a warning and brackets the conflict with lines containing >>>>>>> B If there are conflicts, the user should edit the result and delete one of -the alternatives. When `--ours` or `--theirs` option is in effect, however, -these conflicts are resolved favouring lines from `<current-file>` or -lines from `<other-file>` respectively. +the alternatives. When `--ours`, `--theirs`, or `--union` option is in effect, +however, these conflicts are resolved favouring lines from `<current-file>`, +lines from `<other-file>`, or lines from both respectively. The length of the +conflict markers can be given with the `--marker-size` option. The exit value of this program is negative on error, and the number of conflicts otherwise. If the merge was clean, the exit value is 0. @@ -67,8 +68,9 @@ OPTIONS --ours:: --theirs:: +--union:: Instead of leaving conflicts in the file, resolve conflicts - favouring our (or their) side of the lines. + favouring our (or their or both) side of the lines. EXAMPLES diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index d4487ca..4e5113b 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -3,57 +3,146 @@ git-notes(1) NAME ---- -git-notes - Add/inspect commit notes +git-notes - Add/inspect object notes SYNOPSIS -------- [verse] -'git notes' (edit [-F <file> | -m <msg>] | show) [commit] +'git notes' [list [<object>]] +'git notes' add [-f] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' copy [-f] ( --stdin | <from-object> <to-object> ) +'git notes' append [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' edit [<object>] +'git notes' show [<object>] +'git notes' remove [<object>] +'git notes' prune + DESCRIPTION ----------- -This command allows you to add notes to commit messages, without -changing the commit. To discern these notes from the message stored -in the commit object, the notes are indented like the message, after -an unindented line saying "Notes:". +This command allows you to add/remove notes to/from objects, without +changing 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 +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). -To disable commit notes, you have to set the config variable -core.notesRef to the empty string. Alternatively, you can set it -to a different ref, something like "refs/notes/bugzilla". This setting -can be overridden by the environment variable "GIT_NOTES_REF". +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. + +See the description of "notes.rewrite.<command>" in +linkgit:git-config[1] for a way of carrying your notes across commands +that rewrite commits. SUBCOMMANDS ----------- +list:: + List the notes object for a given object. If no object is + given, show a list of all note objects and the objects they + annotate (in the format "<note object> <annotated object>"). + This is the default subcommand if no subcommand is given. + +add:: + Add notes for a given object (defaults to HEAD). Abort if the + object already has notes (use `-f` to overwrite an + existing note). + +copy:: + Copy the notes for the first object onto the second object. + Abort if the second object already has notes, or if the first + object has none (use -f to overwrite existing notes to the + second object). This subcommand is equivalent to: + `git notes add [-f] -C $(git notes list <from-object>) <to-object>` ++ +In `\--stdin` mode, take lines in the format ++ +---------- +<from-object> SP <to-object> [ SP <rest> ] LF +---------- ++ +on standard input, and copy the notes from each <from-object> to its +corresponding <to-object>. (The optional `<rest>` is ignored so that +the command can read the input given to the `post-rewrite` hook.) + +append:: + Append to the notes of an existing object (defaults to HEAD). + Creates a new notes object if needed. + edit:: - Edit the notes for a given commit (defaults to HEAD). + Edit the notes for a given object (defaults to HEAD). show:: - Show the notes for a given commit (defaults to HEAD). + Show the notes for a given object (defaults to HEAD). + +remove:: + Remove the notes for a given object (defaults to HEAD). + This is equivalent to specifying an empty note message to + the `edit` subcommand. +prune:: + Remove all notes for non-existing/unreachable objects. OPTIONS ------- +-f:: +--force:: + When adding notes to an object that already has notes, + overwrite the existing notes (instead of aborting). + -m <msg>:: +--message=<msg>:: Use the given note message (instead of prompting). - If multiple `-m` (or `-F`) options are given, their - values are concatenated as separate paragraphs. + If multiple `-m` options are given, their values + are concatenated as separate paragraphs. -F <file>:: +--file=<file>:: Take the note message from the given file. Use '-' to read the note message from the standard input. - If multiple `-F` (or `-m`) options are given, their - values are concatenated as separate paragraphs. + +-C <object>:: +--reuse-message=<object>:: + Reuse the note message from the given note object. + +-c <object>:: +--reedit-message=<object>:: + Like '-C', but with '-c' the editor is invoked, so that + 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 + is taken to be in `refs/notes/` if it is not qualified. + + +NOTES +----- + +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`. + +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. Author ------ -Written by Johannes Schindelin <johannes.schindelin@gmx.de> +Written by Johannes Schindelin <johannes.schindelin@gmx.de> and +Johan Herland <johan@herland.net> Documentation ------------- -Documentation by Johannes Schindelin +Documentation by Johannes Schindelin and Johan Herland GIT --- diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 31f42ea..ab4de10 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -31,6 +31,16 @@ in a state that is hard to back out of in the case of a conflict. OPTIONS ------- +-q:: +--quiet:: + This is passed to both underlying git-fetch to squelch reporting of + during transfer, and underlying git-merge to squelch output during + merging. + +-v:: +--verbose:: + Pass --verbose to git-fetch and git-merge. + Options related to merging ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 7a4e507..4857024 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -146,14 +146,21 @@ useful if you write an alias or script around 'git push'. receiver share many of the same objects in common. The default is \--thin. +-q:: +--quiet:: + Suppress all output, including the listing of updated refs, + unless an error occurs. Progress is not reported to the standard + error stream. + -v:: --verbose:: Run verbosely. --q:: ---quiet:: - Suppress all output, including the listing of updated refs, - unless an error occurs. +--progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless -q + is specified. This flag forces progress status even if the + standard error stream is not directed to a terminal. include::urls-remotes.txt[] diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 823f2a4..5863dec 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -274,9 +274,16 @@ which makes little sense. -f:: --force-rebase:: Force the rebase even if the current branch is a descendant - of the commit you are rebasing onto. Normally the command will + of the commit you are rebasing onto. Normally non-interactive rebase will exit with the message "Current branch is up to date" in such a situation. + Incompatible with the --interactive option. ++ +You may find this (or --no-ff with an interactive rebase) helpful after +reverting a topic branch merge, as this option recreates the topic branch with +fresh commits so it can be remerged successfully without needing to "revert +the reversion" (see the +link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). --ignore-whitespace:: --whitespace=<option>:: @@ -288,6 +295,7 @@ which makes little sense. --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:: @@ -316,7 +324,19 @@ which makes little sense. commit to be modified, and change the action of the moved commit from `pick` to `squash` (or `fixup`). + -This option is only valid when '--interactive' option is used. +This option is only valid when the '--interactive' option is used. + +--no-ff:: + With --interactive, cherry-pick all rebased commits instead of + fast-forwarding over the unchanged ones. This ensures that the + entire history of the rebased branch is composed of new commits. ++ +Without --interactive, this is a synonym for --force-rebase. ++ +You may find this helpful after reverting a topic branch merge, as this option +recreates the topic branch with fresh commits so it can be remerged +successfully without needing to "revert the reversion" (see the +link:howto/revert-a-faulty-merge.txt[revert-a-faulty-merge How-To] for details). include::merge-strategies.txt[] diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 1b5f61a..3a23477 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -3,20 +3,69 @@ git-remote-helpers(1) NAME ---- -git-remote-helpers - Helper programs for interoperation with remote git +git-remote-helpers - Helper programs to interact with remote repositories SYNOPSIS -------- -'git remote-<transport>' <remote> +'git remote-<transport>' <repository> [<URL>] DESCRIPTION ----------- -These programs are normally not used directly by end users, but are -invoked by various git programs that interact with remote repositories -when the repository they would operate on will be accessed using -transport code not linked into the main git binary. Various particular -helper programs will behave as documented here. +Remote helper programs are normally not used directly by end users, +but they are invoked by git when it needs to interact with remote +repositories git does not support natively. A given helper will +implement a subset of the capabilities documented here. When git +needs to interact with a repository using a remote helper, it spawns +the helper as an independent process, sends commands to the helper's +standard input, and expects results from the helper's standard +output. Because a remote helper runs as an independent process from +git, there is no need to re-link git to add a new helper, nor any +need to link the helper with the implementation of git. + +Every helper must support the "capabilities" command, which git will +use to determine what other commands the helper will accept. Other +commands generally concern facilities like discovering and updating +remote refs, transporting objects between the object database and +the remote repository, and updating the local object store. + +Helpers supporting the 'fetch' capability can discover refs from the +remote repository and transfer objects reachable from those refs to +the local object store. Helpers supporting the 'push' capability can +transfer local objects to the remote repository and update remote refs. + +Git comes with a "curl" family of remote helpers, that handle various +transport protocols, such as 'git-remote-http', 'git-remote-https', +'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities +'fetch', 'option', and 'push'. + +INVOCATION +---------- + +Remote helper programs are invoked with one or (optionally) two +arguments. The first argument specifies a remote repository as in git; +it is either the name of a configured remote or a URL. The second +argument specifies a URL; it is usually of the form +'<transport>://<address>', but any arbitrary string is possible. + +When git encounters a URL of the form '<transport>://<address>', where +'<transport>' is a protocol that it cannot handle natively, it +automatically invokes 'git remote-<transport>' with the full URL as +the second argument. If such a URL is encountered directly on the +command line, the first argument is the same as the second, and if it +is encountered in a configured remote, the first argument is the name +of that remote. + +A URL of the form '<transport>::<address>' explicitly instructs git to +invoke 'git remote-<transport>' with '<address>' as the second +argument. If such a URL is encountered directly on the command line, +the first argument is '<address>', and if it is encountered in a +configured remote, the first argument is the name of that remote. + +Additionally, when a configured remote has 'remote.<name>.vcs' set to +'<transport>', git explicitly invokes 'git remote-<transport>' with +'<name>' as the first argument. If set, the second argument is +'remote.<name>.url'; otherwise, the second argument is omitted. COMMANDS -------- @@ -25,8 +74,8 @@ Commands are given by the caller on the helper's standard input, one per line. 'capabilities':: Lists the capabilities of the helper, one per line, ending - with a blank line. Each capability may be preceded with '*'. - This marks them mandatory for git version using the remote + with a blank line. Each capability may be preceded with '*', + which marks them mandatory for git version using the remote helper to understand (unknown mandatory capability is fatal error). @@ -35,27 +84,27 @@ Commands are given by the caller on the helper's standard input, one per line. [<attr> ...]". The value may be a hex sha1 hash, "@<dest>" for a symref, or "?" to indicate that the helper could not get the value of the ref. A space-separated list of attributes follows - the name; unrecognized attributes are ignored. After the - complete list, outputs a blank line. + the name; unrecognized attributes are ignored. The list ends + with a blank line. + If 'push' is supported this may be called as 'list for-push' to obtain the current refs prior to sending one or more 'push' commands to the helper. 'option' <name> <value>:: - Set the transport helper option <name> to <value>. Outputs a + Sets the transport helper option <name> to <value>. Outputs a single line containing one of 'ok' (option successfully set), 'unsupported' (option not recognized) or 'error <msg>' - (option <name> is supported but <value> is not correct + (option <name> is supported but <value> is not valid for it). Options should be set before other commands, - and may how those commands behave. + and may influence the behavior of those commands. + Supported if the helper has the "option" capability. 'fetch' <sha1> <name>:: Fetches the given object, writing the necessary objects to the database. Fetch commands are sent in a batch, one - per line, and the batch is terminated with a blank line. + per line, terminated with a blank line. Outputs a single blank line when all fetch commands in the same batch are complete. Only objects which were reported in the ref list with a sha1 may be fetched this way. @@ -67,7 +116,7 @@ suitably updated. Supported if the helper has the "fetch" capability. 'push' +<src>:<dst>:: - Pushes the given <src> commit or branch locally to the + Pushes the given local <src> commit or branch to the remote branch described by <dst>. A batch sequence of one or more push commands is terminated with a blank line. + @@ -91,6 +140,9 @@ Supported if the helper has the "push" capability. by applying the refspecs from the "refspec" capability to the name of the ref. + +Especially useful for interoperability with a foreign versioning +system. ++ Supported if the helper has the "import" capability. 'connect' <service>:: @@ -119,16 +171,11 @@ CAPABILITIES ------------ 'fetch':: - This helper supports the 'fetch' command. - 'option':: - This helper supports the option command. - 'push':: - This helper supports the 'push' command. - 'import':: - This helper supports the 'import' command. +'connect':: + This helper supports the corresponding command with the same name. 'refspec' 'spec':: When using the import command, expect the source ref to have @@ -140,9 +187,6 @@ CAPABILITIES all, it must cover all refs reported by the list command; if it is not used, it is effectively "*:*" -'connect':: - This helper supports the 'connect' command. - REF LIST ATTRIBUTES ------------------- @@ -158,19 +202,19 @@ REF LIST ATTRIBUTES OPTIONS ------- 'option verbosity' <N>:: - Change the level of messages displayed by the helper. - When N is 0 the end-user has asked the process to be - quiet, and the helper should produce only error output. - N of 1 is the default level of verbosity, higher values + Changes the verbosity of messages displayed by the helper. + A value of 0 for N means that processes operate + quietly, and the helper produces only error output. + 1 is the default level of verbosity, and higher values of N correspond to the number of -v flags passed on the command line. 'option progress' \{'true'|'false'\}:: - Enable (or disable) progress messages displayed by the + Enables (or disables) progress messages displayed by the transport helper during a command. 'option depth' <depth>:: - Deepen the history of a shallow repository. + Deepens the history of a shallow repository. 'option followtags' \{'true'|'false'\}:: If enabled the helper should automatically fetch annotated @@ -186,11 +230,15 @@ OPTIONS helpers this only applies to the 'push', if supported. 'option servpath <c-style-quoted-path>':: - Set service path (--upload-pack, --receive-pack etc.) for - next connect. Remote helper MAY support this option. Remote - helper MUST NOT rely on this option being set before + Sets service path (--upload-pack, --receive-pack etc.) for + next connect. Remote helper may support this option, but + must not rely on this option being set before connect request occurs. +SEE ALSO +-------- +linkgit:git-remote[1] + Documentation ------------- Documentation by Daniel Barkalow and Ilari Liusvaara diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 3fc599c..ebaaadc 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>) @@ -51,6 +51,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-reset.txt b/Documentation/git-reset.txt index 168db08..645f0c1 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -8,7 +8,7 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- [verse] -'git reset' [--mixed | --soft | --hard | --merge] [-q] [<commit>] +'git reset' [--mixed | --soft | --hard | --merge | --keep] [-q] [<commit>] 'git reset' [-q] [<commit>] [--] <paths>... 'git reset' --patch [<commit>] [--] [<paths>...] @@ -52,6 +52,14 @@ OPTIONS and updates the files that are different between the named commit and the current commit in the working tree. +--keep:: + Reset the index to the given commit, keeping local changes in + the working tree since the current commit, while updating + working tree files without local changes to what appears in + the given commit. If a file that is different between the + current commit and the given commit has local changes, reset + is aborted. + -p:: --patch:: Interactively select hunks in the difference between the index @@ -93,6 +101,7 @@ in the index and in state D in HEAD. --mixed A D D --hard D D D --merge (disallowed) + --keep (disallowed) working index HEAD target working index HEAD ---------------------------------------------------- @@ -100,6 +109,7 @@ in the index and in state D in HEAD. --mixed A C C --hard C C C --merge (disallowed) + --keep A C C working index HEAD target working index HEAD ---------------------------------------------------- @@ -107,6 +117,7 @@ in the index and in state D in HEAD. --mixed B D D --hard D D D --merge D D D + --keep (disallowed) working index HEAD target working index HEAD ---------------------------------------------------- @@ -114,6 +125,7 @@ in the index and in state D in HEAD. --mixed B C C --hard C C C --merge C C C + --keep B C C working index HEAD target working index HEAD ---------------------------------------------------- @@ -121,6 +133,7 @@ in the index and in state D in HEAD. --mixed B D D --hard D D D --merge (disallowed) + --keep (disallowed) working index HEAD target working index HEAD ---------------------------------------------------- @@ -128,6 +141,7 @@ in the index and in state D in HEAD. --mixed B C C --hard C C C --merge B C C + --keep B C C "reset --merge" is meant to be used when resetting out of a conflicted merge. Any mergy operation guarantees that the work tree file that is @@ -138,6 +152,15 @@ between the index and the work tree, then it means that we are not resetting out from a state that a mergy operation left after failing with a conflict. That is why we disallow --merge option in this case. +"reset --keep" is meant to be used when removing some of the last +commits in the current branch while keeping changes in the working +tree. If there could be conflicts between the changes in the commit we +want to remove and the changes in the working tree we want to keep, +the reset is disallowed. That's why it is disallowed if there are both +changes between the working tree and HEAD, and between HEAD and the +target. To be safe, it is also disallowed when there are unmerged +entries. + The following tables show what happens when there are unmerged entries: @@ -147,6 +170,7 @@ entries: --mixed X B B --hard B B B --merge B B B + --keep (disallowed) working index HEAD target working index HEAD ---------------------------------------------------- @@ -154,6 +178,7 @@ entries: --mixed X A A --hard A A A --merge A A A + --keep (disallowed) X means any state and U means an unmerged index. @@ -325,6 +350,32 @@ $ git add frotz.c <3> <2> This commits all other changes in the index. <3> Adds the file to the index again. +Keep changes in working tree while discarding some previous commits:: ++ +Suppose you are working on something and you commit it, and then you +continue working a bit more, but now you think that what you have in +your working tree should be in another branch that has nothing to do +with what you commited previously. You can start a new branch and +reset it while keeping the changes in your work tree. ++ +------------ +$ git tag start +$ git checkout -b branch1 +$ edit +$ git commit ... <1> +$ edit +$ git checkout -b branch2 <2> +$ git reset --keep start <3> +------------ ++ +<1> This commits your first edits in branch1. +<2> In the ideal world, you could have realized that the earlier + commit did not belong to the new topic when you created and switched + to branch2 (i.e. "git checkout -b branch2 start"), but nobody is + perfect. +<3> But you can use "reset --keep" to remove the unwanted commit after + you switched to "branch2". + Author ------ Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index ced35b2..12622fc 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 dfd4d0c..bc1ac77 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-show-branch.txt b/Documentation/git-show-branch.txt index b9c4154..f1499bb 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order] - [--current] [--color | --no-color] [--sparse] + [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [<rev> | <glob>]... @@ -117,13 +117,15 @@ OPTIONS When no explicit <ref> parameter is given, it defaults to the current branch (or `HEAD` if it is detached). ---color:: +--color[=<when>]:: Color the status sign (one of these: `*` `!` `+` `-`) of each commit corresponding to the branch it's in. + The value must be always (the default), never, or auto. --no-color:: Turn off colored output, even when the configuration file gives the default to color output. + Same as `--color=never`. Note that --more, --list, --independent and --merge-base options are mutually exclusive. diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 1cab91b..2d4bbfc 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -72,21 +72,37 @@ In short-format, the status of each path is shown as where `PATH1` is the path in the `HEAD`, and ` -> PATH2` part is shown only when `PATH1` corresponds to a different path in the -index/worktree (i.e. renamed). - -For unmerged entries, `X` shows the status of stage #2 (i.e. ours) and `Y` -shows the status of stage #3 (i.e. theirs). - -For entries that do not have conflicts, `X` shows the status of the index, -and `Y` shows the status of the work tree. For untracked paths, `XY` are -`??`. +index/worktree (i.e. the file is renamed). The 'XY' is a two-letter +status code. + +The fields (including the `->`) are separated from each other by a +single space. If a filename contains whitespace or other nonprintable +characters, that field will be quoted in the manner of a C string +literal: surrounded by ASCII double quote (34) characters, and with +interior special characters backslash-escaped. + +For paths with merge conflicts, `X` and 'Y' show the modification +states of each side of the merge. For paths that do not have merge +conflicts, `X` shows the status of the index, and `Y` shows the status +of the work tree. For untracked paths, `XY` are `??`. Other status +codes can be interpreted as follows: + +* ' ' = unmodified +* 'M' = modified +* 'A' = added +* 'D' = deleted +* 'R' = renamed +* 'C' = copied +* 'U' = updated but unmerged + +Ignored files are not listed. X Y Meaning ------------------------------------------------- [MD] not updated M [ MD] updated in index A [ MD] added to index - D [ MD] deleted from index + D [ M] deleted from index R [ MD] renamed in index C [ MD] copied in index [MARC] index and work tree matches @@ -104,6 +120,15 @@ and `Y` shows the status of the work tree. For untracked paths, `XY` are ? ? untracked ------------------------------------------------- +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 +order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL +(ASCII 0) follows each filename, replacing space as a field separator +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. CONFIGURATION ------------- diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 99f3c1e..b09bd97 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.txt b/Documentation/git.txt index fbae995..bec6348 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 @@ -43,9 +44,15 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.7.0.5/git.html[documentation for release 1.7.0.5] +* link:v1.7.1/git.html[documentation for release 1.7.1] * release notes for + link:RelNotes-1.7.1.txt[1.7.1]. + +* link:v1.7.0.6/git.html[documentation for release 1.7.0.6] + +* release notes for + link:RelNotes-1.7.0.6.txt[1.7.0.6], link:RelNotes-1.7.0.5.txt[1.7.0.5], link:RelNotes-1.7.0.4.txt[1.7.0.4], link:RelNotes-1.7.0.3.txt[1.7.0.3], @@ -222,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 @@ -532,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 d892e64..0523a57 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 9de8caf..5d91a7e 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/githooks.txt b/Documentation/githooks.txt index 87e2c03..7183aa9 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -317,6 +317,44 @@ This hook is invoked by 'git gc --auto'. It takes no parameter, and exiting with non-zero status from this script causes the 'git gc --auto' to abort. +post-rewrite +~~~~~~~~~~~~ + +This hook is invoked by commands that rewrite commits (`git commit +--amend`, 'git-rebase'; currently 'git-filter-branch' does 'not' call +it!). Its first argument denotes the command it was invoked by: +currently one of `amend` or `rebase`. Further command-dependent +arguments may be passed in the future. + +The hook receives a list of the rewritten commits on stdin, in the +format + + <old-sha1> SP <new-sha1> [ SP <extra-info> ] LF + +The 'extra-info' is again command-dependent. If it is empty, the +preceding SP is also omitted. Currently, no commands pass any +'extra-info'. + +The hook always runs after the automatic note copying (see +"notes.rewrite.<command>" in linkgit:git-config.txt) has happened, and +thus has access to these notes. + +The following command-specific comments apply: + +rebase:: + For the 'squash' and 'fixup' operation, all commits that were + squashed are listed as being rewritten to the squashed commit. + This means that there will be several lines sharing the same + 'new-sha1'. ++ +The commits are guaranteed to be listed in the order that they were +processed by rebase. + +There is no default 'post-rewrite' hook, but see the +`post-receive-copy-notes` script in `contrib/hooks` for an example +that copies your git-notes to the rewritten commits. + + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.txt index 3b4a390..ff5c0bc 100644 --- a/Documentation/howto/revert-a-faulty-merge.txt +++ b/Documentation/howto/revert-a-faulty-merge.txt @@ -142,6 +142,8 @@ different resolution strategies: revert of a merge was rebuilt from scratch (i.e. rebasing and fixing, as you seem to have interpreted), then re-merging the result without doing anything else fancy would be the right thing to do. + (See the ADDENDUM below for how to rebuild a branch from scratch + without changing its original branching-off point.) However, there are things to keep in mind when reverting a merge (and reverting such a revert). @@ -177,3 +179,91 @@ the answer is: "oops, I really shouldn't have merged it, because it wasn't ready yet, and I really need to undo _all_ of the merge"). So then you really should revert the merge, but when you want to re-do the merge, you now need to do it by reverting the revert. + +ADDENDUM + +Sometimes you have to rewrite one of a topic branch's commits *and* you can't +change the topic's branching-off point. Consider the following situation: + + P---o---o---M---x---x---W---x + \ / + A---B---C + +where commit W reverted commit M because it turned out that commit B was wrong +and needs to be rewritten, but you need the rewritten topic to still branch +from commit P (perhaps P is a branching-off point for yet another branch, and +you want be able to merge the topic into both branches). + +The natural thing to do in this case is to checkout the A-B-C branch and use +"rebase -i P" to change commit B. However this does not rewrite commit A, +because "rebase -i" by default fast-forwards over any initial commits selected +with the "pick" command. So you end up with this: + + P---o---o---M---x---x---W---x + \ / + A---B---C <-- old branch + \ + B'---C' <-- naively rewritten branch + +To merge A-B'-C' into the mainline branch you would still have to first revert +commit W in order to pick up the changes in A, but then it's likely that the +changes in B' will conflict with the original B changes re-introduced by the +reversion of W. + +However, you can avoid these problems if you recreate the entire branch, +including commit A: + + A'---B'---C' <-- completely rewritten branch + / + P---o---o---M---x---x---W---x + \ / + A---B---C + +You can merge A'-B'-C' into the mainline branch without worrying about first +reverting W. Mainline's history would look like this: + + A'---B'---C'------------------ + / \ + P---o---o---M---x---x---W---x---M2 + \ / + A---B---C + +But if you don't actually need to change commit A, then you need some way to +recreate it as a new commit with the same changes in it. The rebase commmand's +--no-ff option provides a way to do this: + + $ git rebase [-i] --no-ff P + +The --no-ff option creates a new branch A'-B'-C' with all-new commits (all the +SHA IDs will be different) even if in the interactive case you only actually +modify commit B. You can then merge this new branch directly into the mainline +branch and be sure you'll get all of the branch's changes. + +You can also use --no-ff in cases where you just add extra commits to the topic +to fix it up. Let's revisit the situation discussed at the start of this howto: + + P---o---o---M---x---x---W---x + \ / + A---B---C----------------D---E <-- fixed-up topic branch + +At this point, you can use --no-ff to recreate the topic branch: + + $ git checkout E + $ git rebase --no-ff P + +yielding + + A'---B'---C'------------D'---E' <-- recreated topic branch + / + P---o---o---M---x---x---W---x + \ / + A---B---C----------------D---E + +You can merge the recreated branch into the mainline without reverting commit W, +and mainline's history will look like this: + + A'---B'---C'------------D'---E' + / \ + P---o---o---M---x---x---W---x---M2 + \ / + A---B---C diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 81ac823..722d704 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -72,6 +72,7 @@ option can be used to override --squash. Synonyms to --stat and --no-stat; these are deprecated and will be removed in the future. +ifndef::git-pull[] -q:: --quiet:: Operate quietly. @@ -79,3 +80,4 @@ option can be used to override --squash. -v:: --verbose:: Be verbose. +endif::git-pull[] diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 1686a54..bd760d3 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -123,6 +123,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 aa96cae..af6d2b9 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -30,9 +30,18 @@ people using 80-column terminals. defaults to UTF-8. --no-notes:: ---show-notes:: +--show-notes[=<ref>]:: Show the notes (see linkgit:git-notes[1]) that annotate the commit, when showing the commit log message. This is the default for `git log`, `git show` and `git whatchanged` commands when there is no `--pretty`, `--format` nor `--oneline` option is given on the command line. ++ +With an optional argument, add this ref to the list of notes. The ref +is taken to be in `refs/notes/` if it is not qualified. + +--[no-]standard-notes:: + Enable or disable populating the notes ref list from the + 'core.notesRef' and 'notes.displayRef' variables (or + corresponding environment overrides). Enabled by default. + See linkgit:git-config[1]. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 81c0e6f..b9fb7a8 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -108,8 +108,8 @@ options may be given. See linkgit:git-diff-files[1] for more options. -c:: - This flag changes the way a merge commit is displayed. It shows - the differences from each of the parents to the merge result + With this option, diff output for a merge commit + shows the differences from each of the parents to the merge result simultaneously instead of showing pairwise diff between a parent and the result one at a time. Furthermore, it lists only files which were modified from all parents. @@ -121,6 +121,15 @@ options may be given. See linkgit:git-diff-files[1] for more options. the parents have only two variants and the merge result picks one of them without modification. +-m:: + + This flag makes the merge commits show the full diff like + regular commits; for each merge parent, a separate log entry + and diff is generated. An exception is that only diff against + the first parent is shown when '--first-parent' option is given; + in that case, the output represents the changes the merge + brought _into_ the then-current branch. + -r:: Show recursive diffs. diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 50f9e9a..312e3b2 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -115,6 +115,9 @@ There are some macros to easily define options: `OPT__ABBREV(&int_var)`:: Add `\--abbrev[=<n>]`. +`OPT__COLOR(&int_var, description)`:: + Add `\--color[=<when>]` and `--no-color`. + `OPT__DRY_RUN(&int_var)`:: Add `-n, \--dry-run`. @@ -183,6 +186,15 @@ There are some macros to easily define options: arguments. Short options that happen to be digits take precedence over it. +`OPT_COLOR_FLAG(short, long, &int_var, description)`:: + Introduce an option that takes an optional argument that can + have one of three values: "always", "never", or "auto". If the + argument is not given, it defaults to "always". The `--no-` form + works like `--long=never`; it cannot take an argument. If + "always", set `int_var` to 1; if "never", set `int_var` to 0; if + "auto", set `int_var` to 1 if stdout is a tty or a pager, + 0 otherwise. + The last element of the array must be `OPT_END()`. diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index 293bb15..6d8c24b 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -104,8 +104,12 @@ write `string_list_insert(...)->util = ...;`. `unsorted_string_list_has_string`:: It's like `string_list_has_string()` but for unsorted lists. + +`unsorted_string_list_lookup`:: + + It's like `string_list_lookup()` but for unsorted lists. + -This function needs to look through all items, as opposed to its +The above two functions need to look through all items, as opposed to their counterpart for sorted lists, which performs a binary search. Data structures diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 459a394..1dcd1e7 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -1,44 +1,57 @@ GIT URLS[[URLS]] ---------------- -One of the following notations can be used -to name the remote repository: +In general, URLs contain information about the transport protocol, the +address of the remote server, and the path to the repository. +Depending on the transport protocol, some of this information may be +absent. + +Git natively supports ssh, git, http, https, ftp, ftps, and rsync +protocols. The following syntaxes may be used with them: -- rsync://host.xz/path/to/repo.git/ -- http://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- https://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- git://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- git://host.xz{startsb}:port{endsb}/~user/path/to/repo.git/ - ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/ -- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/ -- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/ -- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git +- git://host.xz{startsb}:port{endsb}/path/to/repo.git/ +- http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ +- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ +- rsync://host.xz/path/to/repo.git/ -SSH is the default transport protocol over the network. You can -optionally specify which user to log-in as, and an alternate, -scp-like syntax is also supported. Both syntaxes support -username expansion, as does the native git protocol, but -only the former supports port specification. The following -three are identical to the last three above, respectively: +An alternative scp-like syntax may also be used with the ssh protocol: -- {startsb}user@{endsb}host.xz:/path/to/repo.git/ -- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/ -- {startsb}user@{endsb}host.xz:path/to/repo.git +- {startsb}user@{endsb}host.xz:path/to/repo.git/ -To sync with a local directory, you can use: +The ssh and git protocols additionally support ~username expansion: + +- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/ +- git://host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/ +- {startsb}user@{endsb}host.xz:/~{startsb}user{endsb}/path/to/repo.git/ + +For local respositories, also supported by git natively, the following +syntaxes may be used: - /path/to/repo.git/ - file:///path/to/repo.git/ ifndef::git-clone[] -They are mostly equivalent, except when cloning. See -linkgit:git-clone[1] for details. +These two syntaxes are mostly equivalent, except when cloning, when +the former implies --local option. See linkgit:git-clone[1] for +details. endif::git-clone[] ifdef::git-clone[] -They are equivalent, except the former implies --local option. +These two syntaxes are mostly equivalent, except the former implies +--local option. endif::git-clone[] +When git doesn't know how to handle a certain transport protocol, it +attempts to use the 'remote-<transport>' remote helper, if one +exists. To explicitly request a remote helper, the following syntax +may be used: + +- <transport>::<address> + +where <address> may be a path, a server and path, or an arbitrary +URL-like string recognized by the specific remote helper being +invoked. See linkgit:git-remote-helpers[1] for details. If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you |