diff options
Diffstat (limited to 'Documentation')
28 files changed, 478 insertions, 195 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 8a8a3954dc..04f69cf64e 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.4.txt b/Documentation/RelNotes-1.7.0.4.txt index cbc94a2f08..cf7f60e60d 100644 --- a/Documentation/RelNotes-1.7.0.4.txt +++ b/Documentation/RelNotes-1.7.0.4.txt @@ -1,9 +1,11 @@ -Git v1.7.0.4 Release Notes (draft) -================================== +Git v1.7.0.4 Release Notes +========================== Fixes since v1.7.0.3 -------------------- + * Optimized ntohl/htonl on big-endian machines were broken. + * Color values given to "color.<cmd>.<slot>" configuration can now have more than one attributes (e.g. "bold ul"). @@ -16,4 +18,10 @@ Fixes since v1.7.0.3 * "git fast-export" didn't check error status and stop when marks file cannot be opened. + * "git format-patch --ignore-if-in-upstream" gave unwarranted errors + when the range was empty, instead of silently finishing. + + * "git remote prune" did not detect remote tracking refs that became + dangling correctly. + And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes-1.7.0.5.txt b/Documentation/RelNotes-1.7.0.5.txt new file mode 100644 index 0000000000..3149c91b7b --- /dev/null +++ b/Documentation/RelNotes-1.7.0.5.txt @@ -0,0 +1,26 @@ +Git v1.7.0.5 Release Notes +========================== + +Fixes since v1.7.0.4 +-------------------- + + * "git daemon" failed to compile on platforms without sockaddr_storage type. + + * Output from "git rev-list --pretty=oneline" was unparsable when a + commit did not have any message, which is abnormal but possible in a + repository converted from foreign scm. + + * "git stash show <commit-that-is-not-a-stash>" gave an error message + that was not so useful. Reworded the message to "<it> is not a + stash". + + * Python scripts in contrib/ area now start with "#!/usr/bin/env python" + to honor user's PATH. + + * "git imap-send" used to mistake any line that begins with "From " as a + message separator in format-patch output. + + * Smart http server backend failed to report an internal server error and + infinitely looped instead after output pipe was closed. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes-1.7.0.6.txt b/Documentation/RelNotes-1.7.0.6.txt new file mode 100644 index 0000000000..b2852b67d0 --- /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 index 19aeef5eff..9d89fedb36 100644 --- a/Documentation/RelNotes-1.7.1.txt +++ b/Documentation/RelNotes-1.7.1.txt @@ -1,19 +1,30 @@ -Git v1.7.1 Release Notes (draft) -================================ +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 - password can be told to use an external program given via GIT_ASKPASS. + 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 - mixture of changes to files with and without CRLF line endings. + 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 descries dirty submodules. + * "git diff --submodule" notices and describes dirty submodules. * "git for-each-ref" learned %(symref), %(symref:short) and %(flag) tokens. @@ -34,12 +45,11 @@ Updates since v1.7.0 * "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 use - the "union merge" behaviour. + * "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 quite a - many commands and features to help you carry notes forward across - rebases and amends. + * "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. @@ -48,13 +58,18 @@ Updates since v1.7.0 near the tip while preserving your local changes in a way similar to how "git checkout branch" does. - * "git status" notices and descries dirty submodules. + * "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 ------------------ @@ -64,8 +79,11 @@ release, unless otherwise noted. * "git add frotz/nitfol" did not complain when the entire frotz/ directory was ignored. ---- -exec >/var/tmp/1 -echo O=$(git describe) -O=v1.7.0.3-310-g99f5b08 -git shortlog --no-merges ^maint $O.. + * "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/SubmittingPatches b/Documentation/SubmittingPatches index c686f8646b..abc65de946 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -520,11 +520,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 +536,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. -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. + $ git format-patch --cover-letter -M --stdout origin/master | git imap-send - $ git format-patch -M --stdout origin/master | git imap-send +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). -Go to your Gmail account, open the Drafts folder, find the patch email, fill -in the To: and CC: fields and send away! +Alternatively, you can use "git send-email" and send your patches +through the GMail SMTP server. edit ~/.gitconfig to specify your +account settings: + +[sendemail] + smtpencryption = tls + smtpserver = smtp.gmail.com + smtpuser = user@gmail.com + smtppass = p4ssw0rd + smtpserverport = 587 + +Once your commits are ready to be sent to the mailing list, run the +following commands: + $ git format-patch --cover-letter -M origin/master -o outgoing/ + $ git send-email outgoing/* diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 4833cac4b9..d8205691c6 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -79,14 +79,15 @@ of lines before or after the line given by <start>. of the --date option at linkgit:git-log[1]. -M|<num>|:: - Detect moving lines in the file as well. When a commit - moves a block of lines in a file (e.g. the original file - has A and then B, and the commit changes it to B and - then A), the traditional 'blame' algorithm typically blames - the lines that were moved up (i.e. B) to the parent and - assigns blame to the lines that were moved down (i.e. A) - to the child commit. With this option, both groups of lines - are blamed on the parent. + Detect moved or copied lines within a file. When a commit + moves or copies a block of lines (e.g. the original file + has A and then B, and the commit changes it to B and then + A), the traditional 'blame' algorithm notices only half of + the movement and typically blames the lines that were moved + up (i.e. B) to the parent and assigns blame to the lines that + were moved down (i.e. A) to the child commit. With this + option, both groups of lines are blamed on the parent by + running extra passes of inspection. + <num> is optional but it is the lower bound on the number of alphanumeric characters that git must detect as moving @@ -94,7 +95,7 @@ within a file for it to associate those lines with the parent commit. -C|<num>|:: - In addition to `-M`, detect lines copied from other + In addition to `-M`, detect lines moved or copied from other files that were modified in the same commit. This is useful when you reorganize your program and move code around across files. When this option is given twice, diff --git a/Documentation/config.txt b/Documentation/config.txt index 9bb8f3d898..6308026bf6 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]. @@ -916,7 +916,7 @@ format.signoff:: gc.aggressiveWindow:: The window size parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults - to 10. + to 250. gc.auto:: When there are approximately more than this many loose @@ -1361,10 +1361,6 @@ notes.rewrite.<command>:: automatically copies your notes from the original to the rewritten commit. Defaults to `true`, but see "notes.rewriteRef" below. -+ -This setting can be overridden with the `GIT_NOTES_REWRITE_REF` -environment variable, which must be a colon separated list of refs or -globs. notes.rewriteMode:: When copying notes during a rewrite (see the @@ -1384,6 +1380,10 @@ notes.rewriteRef:: + Does not have a default value; you must configure this variable to enable note rewriting. ++ +This setting can be overridden with the `GIT_NOTES_REWRITE_REF` +environment variable, which must be a colon separated list of refs or +globs. pack.window:: The size of the window used by linkgit:git-pack-objects[1] when no diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 60e922e6ef..c9c6c2b1cb 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -94,8 +94,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, diff --git a/Documentation/everyday.txt b/Documentation/everyday.txt index 9310b650d3..e0ba8cc075 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/git-branch.txt b/Documentation/git-branch.txt index 903a690f10..1940256930 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -63,7 +63,9 @@ way to clean up all obsolete remote-tracking branches. OPTIONS ------- -d:: - Delete a branch. The branch must be fully merged in HEAD. + Delete a branch. The branch must be fully merged in its + upstream branch, or in `HEAD` if no upstream was set with + `--track` or `--set-upstream`. -D:: Delete a branch irrespective of its merged status. @@ -72,6 +74,8 @@ OPTIONS Create the branch's reflog. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as "<branchname>@\{yesterday}". + Note that in non-bare repositories, reflogs are usually + enabled by default by the `core.logallrefupdates` config option. -f:: --force:: diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 948ea26c5a..400fe7f956 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -8,13 +8,13 @@ git-fetch - Download objects and refs from another repository SYNOPSIS -------- -'git fetch' <options> <repository> <refspec>... +'git fetch' [<options>] [<repository> [<refspec>...]] -'git fetch' <options> <group> +'git fetch' [<options>] <group> -'git fetch' --multiple <options> [<repository> | <group>]... +'git fetch' --multiple [<options>] [<repository> | <group>]... -'git fetch' --all <options> +'git fetch' --all [<options>] DESCRIPTION diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index 5238820657..277d9e141b 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -35,7 +35,7 @@ These services can be enabled/disabled using the per-repository configuration file: http.getanyfile:: - This serves older Git clients which are unable to use the + This serves Git clients older than version 1.6.6 that are unable to use the upload pack service. When enabled, clients are able to read any file within the repository, including objects that are no longer reachable from a branch but are still present. diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index 6cafbe2ec1..57aba42e66 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -16,7 +16,9 @@ DESCRIPTION This command uploads a mailbox generated with 'git format-patch' into an IMAP drafts folder. This allows patches to be sent as other email is when using mail clients that cannot read mailbox -files directly. +files directly. The command also works with any general mailbox +in which emails have the fields "From", "Date", and "Subject" in +that order. Typical usage is something like: @@ -122,12 +124,6 @@ Thunderbird in particular is known to be problematic. Thunderbird users may wish to visit this web page for more information: http://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email - -BUGS ----- -Doesn't handle lines starting with "From " in the message body. - - Author ------ Derived from isync 1.0.1 by Mike McCormack. diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 9c9618cead..c2325ef90e 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -9,7 +9,8 @@ git-merge - Join two or more development histories together SYNOPSIS -------- [verse] -'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]... +'git merge' [-n] [--stat] [--no-commit] [--squash] + [-s <strategy>] [-X <strategy-option>] [--[no-]rerere-autoupdate] [-m <msg>] <commit>... 'git merge' <msg> HEAD <commit>... diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 59dc8b197e..48570242fb 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] [--repo=<repository>] [-f | --force] [-v | --verbose] [-u | --set-upstream] - [<repository> <refspec>...] + [<repository> [<refspec>...]] DESCRIPTION ----------- diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 823f2a4638..0d07b1b207 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>:: @@ -316,7 +323,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 1b5f61aa0b..3a23477ce7 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-send-email.txt b/Documentation/git-send-email.txt index ced35b2f53..3dfdc7cca6 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -300,6 +300,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-show-ref.txt b/Documentation/git-show-ref.txt index df17d49b87..3f9d9c6db3 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -10,7 +10,7 @@ SYNOPSIS [verse] 'git show-ref' [-q|--quiet] [--verify] [--head] [-d|--dereference] [-s|--hash[=<n>]] [--abbrev[=<n>]] [--tags] - [--heads] [--] <pattern>... + [--heads] [--] [<pattern>...] 'git show-ref' --exclude-existing[=<pattern>] < ref-list DESCRIPTION diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 1cab91b534..2d4bbfcaf4 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.txt b/Documentation/git.txt index 4e00b315ff..c4024d0edd 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,17 @@ 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.3/git.html[documentation for release 1.7.0.3] +* 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], link:RelNotes-1.7.0.2.txt[1.7.0.2], link:RelNotes-1.7.0.1.txt[1.7.0.1], diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index d892e642ed..a8500d1772 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -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/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.txt index 3b4a390005..ff5c0bc27a 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 37ce9a17fc..722d704ff2 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -62,6 +62,11 @@ option can be used to override --squash. is used instead ('git merge-recursive' when merging a single head, 'git merge-octopus' otherwise). +-X <option>:: +--strategy-option=<option>:: + Pass merge strategy specific option through to the merge + strategy. + --summary:: --no-summary:: Synonyms to --stat and --no-stat; these are deprecated and will be @@ -76,8 +81,3 @@ ifndef::git-pull[] --verbose:: Be verbose. endif::git-pull[] - --X <option>:: ---strategy-option=<option>:: - Pass merge strategy specific option through to the merge - strategy. diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index 293bb15d20..6d8c24bb1e 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/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 9a5cdafa9c..369f91d3b9 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -36,7 +36,7 @@ Git Transport The Git transport starts off by sending the command and repository on the wire using the pkt-line format, followed by a NUL byte and a -hostname paramater, terminated by a NUL byte. +hostname parameter, terminated by a NUL byte. 0032git-upload-pack /project.git\0host=myserver.com\0 @@ -331,7 +331,7 @@ An incremental update (fetch) response might look like this: C: 0009done\n - S: 003aACK 74730d410fcb6603ace96f1dc55ea6196122532d\n + S: 0031ACK 74730d410fcb6603ace96f1dc55ea6196122532d\n S: [PACKFILE] ---- @@ -488,7 +488,7 @@ An example client/server communication might look like this: C: 0000 C: [PACKDATA] - S: 000aunpack ok\n - S: 0014ok refs/heads/debug\n - S: 0026ng refs/heads/master non-fast-forward\n + S: 000eunpack ok\n + S: 0018ok refs/heads/debug\n + S: 002ang refs/heads/master non-fast-forward\n ---- diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 459a394dc0..1dcd1e7f1e 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 |