diff options
Diffstat (limited to 'Documentation')
52 files changed, 1202 insertions, 129 deletions
diff --git a/Documentation/.gitattributes b/Documentation/.gitattributes new file mode 100644 index 0000000000..ddb030137d --- /dev/null +++ b/Documentation/.gitattributes @@ -0,0 +1 @@ +*.txt whitespace diff --git a/Documentation/Makefile b/Documentation/Makefile index 7a325462ee..43781fb248 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -45,6 +45,7 @@ man7dir=$(mandir)/man7 ASCIIDOC=asciidoc ASCIIDOC_EXTRA = +MANPAGE_XSL = callouts.xsl INSTALL?=install RM ?= rm -f DOC_REF = origin/man @@ -65,6 +66,7 @@ ASCIIDOC_EXTRA += -a asciidoc7compatible endif ifdef DOCBOOK_XSL_172 ASCIIDOC_EXTRA += -a docbook-xsl-172 +MANPAGE_XSL = manpage-1.72.xsl endif # @@ -159,7 +161,7 @@ $(MAN_HTML): %.html : %.txt %.1 %.5 %.7 : %.xml $(RM) $@ - xmlto -m callouts.xsl man $< + xmlto -m $(MANPAGE_XSL) man $< %.xml : %.txt $(RM) $@+ $@ diff --git a/Documentation/RelNotes-1.5.3.3.txt b/Documentation/RelNotes-1.5.3.3.txt index 2a7bfdd5cc..d213846951 100644 --- a/Documentation/RelNotes-1.5.3.3.txt +++ b/Documentation/RelNotes-1.5.3.3.txt @@ -12,7 +12,7 @@ Fixes since v1.5.3.2 * The default shell on some FreeBSD did not execute the argument parsing code correctly and made git unusable. - * git-svn incorrectly spawned pager even when the user user + * git-svn incorrectly spawned pager even when the user explicitly asked not to. * sample post-receive hook overquoted the envelope sender diff --git a/Documentation/RelNotes-1.5.4.1.txt b/Documentation/RelNotes-1.5.4.1.txt new file mode 100644 index 0000000000..d4e44b8b09 --- /dev/null +++ b/Documentation/RelNotes-1.5.4.1.txt @@ -0,0 +1,17 @@ +GIT v1.5.4.1 Release Notes +========================== + +Fixes since v1.5.4 +------------------ + + * "git-commit -C $tag" used to work but rewrite in C done in + 1.5.4 broke it. + + * An entry in the .gitattributes file that names a pattern in a + subdirectory of the directory it is in did not match + correctly (e.g. pattern "b/*.c" in "a/.gitattributes" should + match "a/b/foo.c" but it didn't). + + * Customized color specification was parsed incorrectly when + numeric color values are used. This was fixed in 1.5.4.1. + diff --git a/Documentation/RelNotes-1.5.4.2.txt b/Documentation/RelNotes-1.5.4.2.txt new file mode 100644 index 0000000000..21d0df59fb --- /dev/null +++ b/Documentation/RelNotes-1.5.4.2.txt @@ -0,0 +1,43 @@ +GIT v1.5.4.2 Release Notes +========================== + +Fixes since v1.5.4 +------------------ + + * The configuration parser was not prepared to see string + valued variables misspelled as boolean and segfaulted. + + * Temporary files left behind due to interrupted object + transfers were not cleaned up with "git prune". + + * "git config --unset" was confused when the unset variables + were spelled with continuation lines in the config file. + + * The merge message detection in "git cvsimport" did not catch + a message that began with "Merge...". + + * "git status" suggests "git rm --cached" for unstaging the + earlier "git add" before the initial commit. + + * "git status" output was incorrect during a partial commit. + + * "git bisect" refused to start when the HEAD was detached. + + * "git bisect" allowed a wildcard character in the commit + message expanded while writing its log file. + + * Manual pages were not formatted correctly with docbook xsl + 1.72; added a workaround. + + * "git-commit -C $tag" used to work but rewrite in C done in + 1.5.4 broke it. This was fixed in 1.5.4.1. + + * An entry in the .gitattributes file that names a pattern in a + subdirectory of the directory it is in did not match + correctly (e.g. pattern "b/*.c" in "a/.gitattributes" should + match "a/b/foo.c" but it didn't). This was fixed in 1.5.4.1. + + * Customized color specification was parsed incorrectly when + numeric color values are used. This was fixed in 1.5.4.1. + + * http transport misbehaved when linked with curl-gnutls. diff --git a/Documentation/RelNotes-1.5.4.3.txt b/Documentation/RelNotes-1.5.4.3.txt new file mode 100644 index 0000000000..b0fc67fb2a --- /dev/null +++ b/Documentation/RelNotes-1.5.4.3.txt @@ -0,0 +1,27 @@ +GIT v1.5.4.3 Release Notes +========================== + +Fixes since v1.5.4.2 +-------------------- + + * RPM spec used to pull in everything with 'git'. This has been + changed so that 'git' package contains just the core parts, + and we now supply 'git-all' metapackage to slurp in everything. + This should match end user's expectation better. + + * When some refs failed to update, git-push reported "failure" + which was unclear if some other refs were updated or all of + them failed atomically (the answer is the former). Reworded + the message to clarify this. + + * "git clone" from a repository whose HEAD was misconfigured + did not set up the remote properly. Now it tries to do + better. + + * Updated git-push documentation to clarify what "matching" + means, in order to reduce user confusion. + + * Updated git-add documentation to clarify "add -u" operates in + the current subdirectory you are in, just like other commands. + + * git-gui updates to work on OSX and Windows better. diff --git a/Documentation/RelNotes-1.5.4.txt b/Documentation/RelNotes-1.5.4.txt index 9c864c9def..f1323b6174 100644 --- a/Documentation/RelNotes-1.5.4.txt +++ b/Documentation/RelNotes-1.5.4.txt @@ -10,22 +10,32 @@ Removal * As git-commit and git-status have been rewritten, "git runstatus" helper script lost all its users and has been removed. - * Curl library older than 7.10 is not supported by "git http-push", - as it does not work without CURLM. + +Temporarily disabled +-------------------- + + * "git http-push" is known not to work well with cURL library older + than 7.16, and we had reports of repository corruption. It is + disabled on such platforms for now. Unfortunately, 1.5.3.8 shares + the same issue. In other words, this does not mean you will be + fine if you stick to an older git release. For now, please do not + use http-push from older git with cURL older than 7.16 if you + value your data. A proper fix will hopefully materialize in + later versions. Deprecation notices ------------------- - * The next feature release of git (this change is scheduled for v1.6.0) - will by default install dashed form of commands (e.g. "git-commit") - outside of users' normal $PATH, and will install only selected - commands ("git" itself, and "gitk") in $PATH. This implies: + * From v1.6.0, git will by default install dashed form of commands + (e.g. "git-commit") outside of users' normal $PATH, and will install + only selected commands ("git" itself, and "gitk") in $PATH. This + implies: - Using dashed forms of git commands (e.g. "git-commit") from the command line has been informally deprecated since early 2006, but now it officially is, and will be removed in the future. Use - dashless forms (e.g. "git commit") instead. + dash-less forms (e.g. "git commit") instead. - Using dashed forms from your scripts, without first prepending the return value from "git --exec-path" to the scripts' PATH, has been @@ -34,8 +44,8 @@ Deprecation notices - Use of dashed forms with "PATH=$(git --exec-path):$PATH; export PATH" early in your script is not deprecated with this change. - Users are strongly encouraged to adjust their habits and scripts now - to prepare for this. + Users are strongly encouraged to adjust their habits and scripts now + to prepare for this change. * The post-receive hook was introduced in March 2007 to supersede the post-update hook, primarily to overcome the command line length @@ -70,7 +80,7 @@ Updates since v1.5.3 * Comes with much improved gitk, with i18n. - * Comes with "git gui" 0.9.1 with i18n. + * Comes with git-gui 0.9.2 with i18n. * gitk is now merged as a subdirectory of git.git project, in preparation for its i18n. @@ -156,7 +166,7 @@ Updates since v1.5.3 command line in the generated log message, when told to cherry-pick a commit by naming a tag that points at it. It does not anymore. - * "git for-each-ref" learned %(xxxdate:<dateformat>) syntax to show the + * "git for-each-ref" learned %(xxxdate:<date-format>) syntax to show the various date fields in different formats. * "git gc --auto" is a low-impact way to automatically run a variant of @@ -211,7 +221,7 @@ Updates since v1.5.3 * "git pull --rebase" is a different way to integrate what you fetched into your current branch. - * "git fast-export" produces datastream that can be fed to fast-import + * "git fast-export" produces data-stream that can be fed to fast-import to reproduce the history recorded in a git repository. * "git add -i" takes pathspecs to limit the set of files to work on. @@ -232,8 +242,8 @@ Updates since v1.5.3 from its first parent. * "git commit" used to unconditionally strip comment lines that - began with '#' and removed excess blank lines. This - behaviour has been made configurable. + began with '#' and removed excess blank lines. This behavior has + been made configurable. * "git commit" has been rewritten in C. @@ -317,7 +327,7 @@ Updates since v1.5.3 * "git status" from a subdirectory now shows relative paths, which makes copy-and-pasting for git-checkout/git-add/git-rm easier. The - traditional behaviour to show the full path relative to the top of + traditional behavior to show the full path relative to the top of the work tree can be had by setting status.relativepaths configuration variable to false. @@ -332,7 +342,7 @@ Updates since v1.5.3 * "git help" learned "-w" option to show documentation in browsers. - * In addition there are quite a few internal clean-ups. Notably + * In addition there are quite a few internal clean-ups. Notably: - many fork/exec have been replaced with run-command API, brought from the msysgit effort. @@ -341,6 +351,7 @@ Updates since v1.5.3 - enhancement and more use of the strbuf API. + * Makefile tweaks to support HP-UX is in. Fixes since v1.5.3 ------------------ @@ -354,7 +365,7 @@ series. * The way "git diff --check" behaves is much more consistent with the way "git apply --whitespace=warn" works. - * "git svn" talking with the SVN over http will correctly quote branch + * "git svn" talking with the SVN over HTTP will correctly quote branch and project names. * "git config" did not work correctly on platforms that define @@ -364,9 +375,3 @@ series. documentation; a workaround has been implemented. * "git diff --color-words" colored context lines in a wrong color. - --- -exec >/var/tmp/1 -O=v1.5.4-rc4 -echo O=`git describe refs/heads/master` -git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/RelNotes-1.5.5.txt b/Documentation/RelNotes-1.5.5.txt new file mode 100644 index 0000000000..c8b4f72c23 --- /dev/null +++ b/Documentation/RelNotes-1.5.5.txt @@ -0,0 +1,78 @@ +GIT v1.5.5 Release Notes +======================== + +Updates since v1.5.4 +-------------------- + +(performance) + + * On platforms with suboptimal qsort(3) implementation, there + is an option to use more reasonable substitute we ship with + our software. + + * New configuration variable "pack.packsizelimit" can be used + in place of command line option --max-pack-size. + + * "git fetch" over the native git protocol used to make a + connection to find out the set of current remote refs and + another to actually download the pack data. We now use only + one connection for these tasks. + + * "git commit" does not run lstat(2) more than necessary + anymore. + +(usability, bells and whistles) + + * You can be warned when core.autocrlf conversion is applied in + such a way that results in an irreversible conversion. + + * A pattern "foo/" in .gitignore file now matches a directory + "foo". Pattern "foo" also matches as before. + + * "git describe" learned to limit the tags to be used for + naming with --match option. + + * "git describe --contains" now barfs when the named commit + cannot be described. + + * bash completion's prompt helper function can talk about + operation in-progress (e.g. merge, rebase, etc.). + + * "git commit" learned a new hook "prepare-commit-msg" that can + inspect what is going to be committed and prepare the commit + log message template to be edited. + + * "git gui" learned an auto-spell checking. + + * "git send-email" learned to prompt for passwords + interactively. + + * "git send-email" learned an easier way to suppress CC + recipients. + + * Various "git cvsimport", "git cvsexportcommit", "git svn" and + "git p4" improvements. + +(internal) + + * Duplicated code between git-help and git-instaweb that + launches user's preferred browser has been refactored. + + * It is now easier to write test scripts that records known + breakages. + + +Fixes since v1.5.4 +------------------ + +All of the fixes in v1.5.4 maintenance series are included in +this release, unless otherwise noted. + + +--- +exec >/var/tmp/1 +O=v1.5.4 +O=v1.5.4.2-122-g7cb97da +echo O=`git describe refs/heads/master` +git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint + diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index de08d094e3..0e155c936c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -34,9 +34,9 @@ Checklist (and a short version for the impatient): - if your name is not writable in ASCII, make sure that you send off a message in the correct encoding. - send the patch to the list (git@vger.kernel.org) and the - maintainer (gitster@pobox.com). If you use - git-send-email(1), please test it first by sending - email to yourself. + maintainer (gitster@pobox.com) if (and only if) the patch + is ready for inclusion. If you use git-send-email(1), + please test it first by sending email to yourself. Long version: @@ -112,7 +112,12 @@ lose tabs that way if you are not careful. It is a common convention to prefix your subject line with [PATCH]. This lets people easily distinguish patches from other -e-mail discussions. +e-mail discussions. Use of additional markers after PATCH and +the closing bracket to mark the nature of the patch is also +encouraged. E.g. [PATCH/RFC] is often used when the patch is +not ready to be applied but it is for discussion, [PATCH v2], +[PATCH v3] etc. are often seen when you are sending an update to +what you have previously sent. "git format-patch" command follows the best current practice to format the body of an e-mail message. At the beginning of the @@ -157,7 +162,8 @@ 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. +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 @@ -210,10 +216,53 @@ then you just add a line saying This line can be automatically added by git if you run the git-commit command with the -s option. -Some people also put extra tags at the end. They'll just be ignored for -now, but you can do this to mark internal company procedures or just -point out some special detail about the sign-off. +Notice that you can place your own Signed-off-by: line when +forwarding somebody else's patch with the above rules for +D-C-O. Indeed you are encouraged to do so. Do not forget to +place an in-body "From: " line at the beginning to properly attribute +the change to its true author (see (2) above). +Some people also put extra tags at the end. + +"Acked-by:" says that the patch was reviewed by the person who +is more familiar with the issues and the area the patch attempts +to modify. "Tested-by:" says the patch was tested by the person +and found to have the desired effect. + +------------------------------------------------ +An ideal patch flow + +Here is an ideal patch flow for this project the current maintainer +suggests to the contributors: + + (0) You come up with an itch. You code it up. + + (1) Send it to the list and cc people who may need to know about + the change. + + The people who may need to know are the ones whose code you + are butchering. These people happen to be the ones who are + most likely to be knowledgeable enough to help you, but + they have no obligation to help you (i.e. you ask for help, + don't demand). "git log -p -- $area_you_are_modifying" would + help you find out who they are. + + (2) You get comments and suggestions for improvements. You may + even get them in a "on top of your change" patch form. + + (3) Polish, refine, and re-send to the list and the people who + spend their time to improve your patch. Go back to step (2). + + (4) The list forms consensus that the last round of your patch is + good. Send it to the list and cc the maintainer. + + (5) A topic branch is created with the patch and is merged to 'next', + and cooked further and eventually graduates to 'master'. + +In any time between the (2)-(3) cycle, the maintainer may pick it up +from the list and queue it to 'pu', in order to make it easier for +people play with it without having to pick up and apply the patch to +their trees themselves. ------------------------------------------------ MUA specific hints diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index ea1007bfb0..c11bb7d36c 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -52,7 +52,7 @@ of lines before or after the line given by <start>. When <rev> is not specified, the command annotates the changes starting backwards from the working tree copy. This flag makes the command pretend as if the working - tree copy has the contents of he named file (specify + tree copy has the contents of the named file (specify `-` to make the command read from the standard input). -M|<num>|:: diff --git a/Documentation/config.txt b/Documentation/config.txt index f5994bd4a7..4027726f2e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -139,6 +139,51 @@ core.autocrlf:: "text" (i.e. be subjected to the autocrlf mechanism) is decided purely based on the contents. +core.safecrlf:: + If true, makes git check if converting `CRLF` as controlled by + `core.autocrlf` is reversible. Git will verify if a command + modifies a file in the work tree either directly or indirectly. + For example, committing a file followed by checking out the + same file should yield the original file in the work tree. If + this is not the case for the current setting of + `core.autocrlf`, git will reject the file. The variable can + be set to "warn", in which case git will only warn about an + irreversible conversion but continue the operation. ++ +CRLF conversion bears a slight chance of corrupting data. +autocrlf=true will convert CRLF to LF during commit and LF to +CRLF during checkout. A file that contains a mixture of LF and +CRLF before the commit cannot be recreated by git. For text +files this is the right thing to do: it corrects line endings +such that we have only LF line endings in the repository. +But for binary files that are accidentally classified as text the +conversion can corrupt data. ++ +If you recognize such corruption early you can easily fix it by +setting the conversion type explicitly in .gitattributes. Right +after committing you still have the original file in your work +tree and this file is not yet corrupted. You can explicitly tell +git that this file is binary and git will handle the file +appropriately. ++ +Unfortunately, the desired effect of cleaning up text files with +mixed line endings and the undesired effect of corrupting binary +files cannot be distinguished. In both cases CRLFs are removed +in an irreversible way. For text files this is the right thing +to do because CRLFs are line endings, while for binary files +converting CRLFs corrupts data. ++ +Note, this safety check does not mean that a checkout will generate a +file identical to the original file for a different setting of +`core.autocrlf`, but only for the current one. For example, a text +file with `LF` would be accepted with `core.autocrlf=input` and could +later be checked out with `core.autocrlf=true`, in which case the +resulting file would contain `CRLF`, although the original file +contained `LF`. However, in both work trees the line endings would be +consistent, that is either all `LF` or all `CRLF`, but never mixed. A +file with mixed line endings would be reported by the `core.safecrlf` +mechanism. + core.symlinks:: If false, symbolic links are checked out as small plain files that contain the link text. linkgit:git-update-index[1] and @@ -308,6 +353,10 @@ 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). +* `cr-at-eol` treats a carriage-return at the end of line as + part of the line terminator, i.e. with it, `trailing-space` + does not trigger if the character before such a carriage-return + is not a whitespace (not enabled by default). alias.*:: Command aliases for the linkgit:git[1] command wrapper - e.g. @@ -371,6 +420,11 @@ branch.<name>.rebase:: it unless you understand the implications (see linkgit:git-rebase[1] for details). +browser.<tool>.path:: + Override the path for the given tool that may be used to + browse HTML help (see '-w' option in linkgit:git-help[1]) or a + working repository in gitweb (see linkgit:git-instaweb[1]). + clean.requireForce:: A boolean to make git-clean do nothing unless given -f or -n. Defaults to true. @@ -443,6 +497,13 @@ color.status.<slot>:: commit.template:: Specify a file to use as the template for new commit messages. +color.ui:: + When set to `always`, always use colors in all git commands which + are capable of colored output. When false (or `never`), never. When + set to `true` or `auto`, use colors only when the output is to the + terminal. When more specific variables of color.* are set, they always + take precedence over this setting. Defaults to false. + diff.autorefreshindex:: When using `git diff` to compare with work tree files, do not consider stat-only change as changed. @@ -755,6 +816,8 @@ pack.threads:: warning. This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. + Specifying 0 will cause git to auto-detect the number of CPU's + and set the number of threads accordingly. pack.indexVersion:: Specify the default pack index version. Valid values are 1 for @@ -765,6 +828,12 @@ pack.indexVersion:: whenever the corresponding pack is larger than 2 GB. Otherwise the default is 1. +pack.packSizeLimit: + The default maximum size of a pack. This setting only affects + packing to a file, i.e. the git:// protocol is unaffected. It + can be overridden by the `\--max-pack-size` option of + linkgit:git-repack[1]. + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. @@ -834,6 +903,17 @@ tar.umask:: archiving user's umask will be used instead. See umask(2) and linkgit:git-archive[1]. +url.<base>.insteadOf:: + Any URL that starts with this value will be rewritten to + start, instead, with <base>. In cases where some site serves a + large number of repositories, and serves them with multiple + access methods, and some users need to use different access + methods, this feature allows people to specify any of the + equivalent URLs and have git automatically rewrite the URL to + the best alternative for the particular user, even for a + never-before-seen repository on the site. When more than one + insteadOf strings match a given URL, the longest match is used. + user.email:: Your email address to be recorded in any newly created commits. Can be overridden by the 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_EMAIL', and diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 8d35cbd60d..8dc5b001c4 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -170,6 +170,14 @@ endif::git-format-patch[] Swap two inputs; that is, show differences from index or on-disk file to tree contents. +--relative[=<path>]:: + When run from a subdirectory of the project, it can be + told to exclude changes outside the directory and show + pathnames relative to it with this option. When you are + not in a subdirectory (e.g. in a bare repository), you + can name which subdirectory to make the output relative + to by giving a <path> as an argument. + --text:: Treat all files as text. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 61e48ccf02..b675911480 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -23,11 +23,15 @@ fetches is a descendant of `<lbranch>`. This option overrides that check. +ifdef::git-pull[] +\--no-tags:: +endif::git-pull[] +ifndef::git-pull[] -n, \--no-tags:: - By default, `git-fetch` fetches tags that point at - objects that are downloaded from the remote repository - and stores them locally. This option disables this - automatic tag following. +endif::git-pull[] + By default, tags that point at objects that are downloaded + from the remote repository are fetched and stored locally. + This option disables this automatic tag following. -t, \--tags:: Most of the tags are fetched automatically as branch diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 9d2ac865d2..47799097ce 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -74,8 +74,8 @@ OPTIONS Update only files that git already knows about. This is similar to what "git commit -a" does in preparation for making a commit, except that the update is limited to paths specified on the - command line. If no paths are specified, all tracked files are - updated. + command line. If no paths are specified, all tracked files in the + current directory and its subdirectories are updated. \--refresh:: Don't add the file(s), but only refresh their stat() diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 2ffba2102b..e640fc75cd 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -138,7 +138,7 @@ aborts in the middle,. You can recover from this in one of two ways: The command refuses to process new mailboxes while `.dotest` directory exists, so if you decide to start over from scratch, -run `rm -f .dotest` before running the command with mailbox +run `rm -f -r .dotest` before running the command with mailbox names. diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 72f080a972..505ac056e6 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -99,36 +99,62 @@ Assume two repositories exist as R1 on machine A, and R2 on machine B. For whatever reason, direct connection between A and B is not allowed, but we can move data from A to B via some mechanism (CD, email, etc). We want to update R2 with developments made on branch master in R1. + +To create the bundle you have to specify the basis. You have some options: + +- Without basis. ++ +This is useful when sending the whole history. + +------------ +$ git bundle create mybundle master +------------ + +- Using temporally tags. ++ We set a tag in R1 (lastR2bundle) after the previous such transport, and move it afterwards to help build the bundle. -in R1 on A: - ------------ $ git-bundle create mybundle master ^lastR2bundle $ git tag -f lastR2bundle master ------------ -(move mybundle from A to B by some mechanism) +- Using a tag present in both repositories + +------------ +$ git bundle create mybundle master ^v1.0.0 +------------ + +- A basis based on time. + +------------ +$ git bundle create mybundle master --since=10.days.ago +------------ -in R2 on B: +- With a limit on the number of commits ------------ -$ git-bundle verify mybundle -$ git-fetch mybundle refspec +$ git bundle create mybundle master -n 10 ------------ -where refspec is refInBundle:localRef +Then you move mybundle from A to B, and in R2 on B: +------------ +$ git-bundle verify mybundle +$ git-fetch mybundle master:localRef +------------ -Also, with something like this in your config: +With something like this in the config in R2: +------------------------ [remote "bundle"] url = /home/me/tmp/file.bdl fetch = refs/heads/*:refs/remotes/origin/* +------------------------ You can first sneakernet the bundle file to ~/tmp/file.bdl and -then these commands: +then these commands on machine B: ------------ $ git ls-remote bundle diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index fdccbd4cbe..975824301a 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -62,6 +62,15 @@ OPTIONS .git/objects/info/alternates to share the objects with the source repository. The resulting repository starts out without any object of its own. ++ +*NOTE*: this is a possibly dangerous operation; do *not* use +it unless you understand what it does. If you clone your +repository using this option, then delete branches in the +source repository and then run linkgit:git-gc[1] using the +'--prune' option in the source repository, it may remove +objects which are referenced by the cloned repository. + + --reference <repository>:: If the reference repository is on the local machine diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index c3725b2ed9..b4ae61ff46 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -280,8 +280,8 @@ order). HOOKS ----- -This command can run `commit-msg`, `pre-commit`, and -`post-commit` hooks. See link:hooks.html[hooks] for more +This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, +and `post-commit` hooks. See link:hooks.html[hooks] for more information. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index e4d0e47529..fa161718dd 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -130,7 +130,7 @@ See also <<FILES>>. -z, --null:: For all options that output values and/or keys, always - end values with with the null character (instead of a + end values with the null character (instead of a newline). Use newline instead as a delimiter between key and value. This allows for secure parsing of the output without getting confused e.g. by values that diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index dbce503694..6f91b9ea2a 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -107,8 +107,8 @@ If you need to pass multiple options, separate them with a comma. -M <regex>:: Attempt to detect merges based on the commit message with a custom - regex. It can be used with '-m' to also see the default regexes. - You must escape forward slashes. + regex. It can be used with '-m' to enable the default regexes + as well. You must escape forward slashes. -S <regex>:: Skip paths matching the regex. diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index d75e401343..d3e99931d7 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -183,7 +183,7 @@ access method and requested operation. That means that even if you offer only read access (e.g. by using the pserver method), git-cvsserver should have write access to the database to work reliably (otherwise you need to make sure -that the database if up-to-date all the time git-cvsserver is run). +that the database is up-to-date any time git-cvsserver is executed). By default it uses SQLite databases in the git directory, named `gitcvs.<module_name>.sqlite`. Note that the SQLite backend creates @@ -204,7 +204,7 @@ about `DBI->connect()`. gitcvs.dbname:: Database name. The exact meaning depends on the - used database driver, for SQLite this is a filename. + selected database driver, for SQLite this is a filename. Supports variable substitution (see below). May not contain semicolons (`;`). Default: '%Ggitcvs.%m.sqlite' @@ -215,7 +215,7 @@ gitcvs.dbdriver:: with 'DBD::SQLite', reported to work with 'DBD::Pg', and reported *not* to work with 'DBD::mysql'. Please regard this as an experimental feature. May not - contain double colons (`:`). + contain colons (`:`). Default: 'SQLite' gitcvs.dbuser:: diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 0742152b81..fbb40a2916 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -45,12 +45,21 @@ OPTIONS candidates to describe the input committish consider up to <n> candidates. Increasing <n> above 10 will take slightly longer but may produce a more accurate result. + An <n> of 0 will cause only exact matches to be output. + +--exact-match:: + Only output exact matches (a tag directly references the + supplied commit). This is a synonym for --candidates=0. --debug:: Verbosely display information about the searching strategy being employed to standard error. The tag name will still be printed to standard out. +--match <pattern>:: + Only consider tags matching the given pattern (can be used to avoid + leaking private tags made from the repository). + EXAMPLES -------- diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index bd625ababf..96f6767075 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -805,6 +805,93 @@ Placing a `progress` command immediately after a `checkpoint` will inform the reader when the `checkpoint` has been completed and it can safely access the refs that fast-import updated. +Crash Reports +------------- +If fast-import is supplied invalid input it will terminate with a +non-zero exit status and create a crash report in the top level of +the Git repository it was importing into. Crash reports contain +a snapshot of the internal fast-import state as well as the most +recent commands that lead up to the crash. + +All recent commands (including stream comments, file changes and +progress commands) are shown in the command history within the crash +report, but raw file data and commit messages are excluded from the +crash report. This exclusion saves space within the report file +and reduces the amount of buffering that fast-import must perform +during execution. + +After writing a crash report fast-import will close the current +packfile and export the marks table. This allows the frontend +developer to inspect the repository state and resume the import from +the point where it crashed. The modified branches and tags are not +updated during a crash, as the import did not complete successfully. +Branch and tag information can be found in the crash report and +must be applied manually if the update is needed. + +An example crash: + +==== + $ cat >in <<END_OF_INPUT + # my very first test commit + commit refs/heads/master + committer Shawn O. Pearce <spearce> 19283 -0400 + # who is that guy anyway? + data <<EOF + this is my commit + EOF + M 644 inline .gitignore + data <<EOF + .gitignore + EOF + M 777 inline bob + END_OF_INPUT + + $ git-fast-import <in + fatal: Corrupt mode: M 777 inline bob + fast-import: dumping crash report to .git/fast_import_crash_8434 + + $ cat .git/fast_import_crash_8434 + fast-import crash report: + fast-import process: 8434 + parent process : 1391 + at Sat Sep 1 00:58:12 2007 + + fatal: Corrupt mode: M 777 inline bob + + Most Recent Commands Before Crash + --------------------------------- + # my very first test commit + commit refs/heads/master + committer Shawn O. Pearce <spearce> 19283 -0400 + # who is that guy anyway? + data <<EOF + M 644 inline .gitignore + data <<EOF + * M 777 inline bob + + Active Branch LRU + ----------------- + active_branches = 1 cur, 5 max + + pos clock name + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 1) 0 refs/heads/master + + Inactive Branches + ----------------- + refs/heads/master: + status : active loaded dirty + tip commit : 0000000000000000000000000000000000000000 + old tree : 0000000000000000000000000000000000000000 + cur tree : 0000000000000000000000000000000000000000 + commit clock: 0 + last pack : + + + ------------------- + END OF CRASH REPORT +==== + Tips and Tricks --------------- The following tips and tricks have been collected from various diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index e22dfa5803..543a1cf105 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -56,7 +56,9 @@ notable exception of the commit filter, for technical reasons). Prior to that, the $GIT_COMMIT environment variable will be set to contain the id of the commit being rewritten. Also, GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, -and GIT_COMMITTER_DATE are set according to the current commit. +and GIT_COMMITTER_DATE are set according to the current commit. If any +evaluation of <command> returns a non-zero exit status, the whole operation +will be aborted. A 'map' function is available that takes an "original sha1 id" argument and outputs a "rewritten sha1 id" if the commit has been already @@ -197,7 +199,7 @@ happened). If this is not the case, use: -------------------------------------------------------------------------- git filter-branch --parent-filter \ - 'cat; test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>"' HEAD + 'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD -------------------------------------------------------------------------- or even simpler: @@ -240,6 +242,15 @@ committed a merge between P1 and P2, it will be propagated properly and all children of the merge will become merge commits with P1,P2 as their parents instead of the merge commit. +You can rewrite the commit log messages using `--message-filter`. For +example, `git-svn-id` strings in a repository created by `git-svn` can +be removed this way: + +------------------------------------------------------- +git filter-branch --message-filter ' + sed -e "/^git-svn-id:/d" +' +------------------------------------------------------- To restrict rewriting to only part of the history, specify a revision range in addition to the new branch name. The new branch name will diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 651efe6ca1..b5207b7604 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -10,13 +10,15 @@ SYNOPSIS -------- [verse] 'git-format-patch' [-k] [-o <dir> | --stdout] [--thread] - [--attach[=<boundary>] | --inline[=<boundary>]] - [-s | --signoff] [<common diff options>] - [-n | --numbered | -N | --no-numbered] - [--start-number <n>] [--numbered-files] - [--in-reply-to=Message-Id] [--suffix=.<sfx>] - [--ignore-if-in-upstream] - [--subject-prefix=Subject-Prefix] + [--attach[=<boundary>] | --inline[=<boundary>]] + [-s | --signoff] [<common diff options>] + [-n | --numbered | -N | --no-numbered] + [--start-number <n>] [--numbered-files] + [--in-reply-to=Message-Id] [--suffix=.<sfx>] + [--ignore-if-in-upstream] + [--subject-prefix=Subject-Prefix] + [--cc=<email>] + [--cover-letter] [ <since> | <revision range> ] DESCRIPTION @@ -135,6 +137,15 @@ include::diff-options.txt[] allows for useful naming of a patch series, and can be combined with the --numbered option. +--cc=<email>:: + Add a "Cc:" header to the email headers. This is in addition + to any configured headers, and may be used multiple times. + +--cover-letter:: + Generate a cover letter template. You still have to fill in + a description, but the shortlog and the diffstat will be + generated for you. + --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index f3cb24f252..71a73354f8 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -75,9 +75,11 @@ OPTIONS -n:: Prefix the line number to matching lines. --l | --files-with-matches | -L | --files-without-match:: +-l | --files-with-matches | --name-only | -L | --files-without-match:: Instead of showing every matched line, show only the names of files that contain (or do not contain) matches. + For better compatability with git-diff, --name-only is a + synonym for --files-with-matches. -c | --count:: Instead of showing every matched line, show the number of diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 09904c75c4..0926dc12ba 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -47,17 +47,9 @@ OPTIONS + The web browser can be specified using the configuration variable 'help.browser', or 'web.browser' if the former is not set. If none of -these config variables is set, the 'git-help--browse' helper script -(called by 'git-help') will pick a suitable default. -+ -You can explicitly provide a full path to your preferred browser by -setting the configuration variable 'browser.<tool>.path'. For example, -you can configure the absolute path to firefox by setting -'browser.firefox.path'. Otherwise, 'git-help--browse' assumes the tool -is available in PATH. -+ -Note that the script tries, as much as possible, to display the HTML -page in a new tab on an already opened browser. +these config variables is set, the 'git-web--browse' helper script +(called by 'git-help') will pick a suitable default. See +linkgit:git-web--browse[1] for more information about this. CONFIGURATION VARIABLES ----------------------- @@ -74,7 +66,7 @@ line option: The 'help.browser', 'web.browser' and 'browser.<tool>.path' will also be checked if the 'web' format is chosen (either by command line option or configuration variable). See '-w|--web' in the OPTIONS -section above. +section above and linkgit:git-web--browse[1]. Note that these configuration variables should probably be set using the '--global' flag, for example like this: diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt index cca77f10d2..0b82722342 100644 --- a/Documentation/git-http-push.txt +++ b/Documentation/git-http-push.txt @@ -15,6 +15,9 @@ DESCRIPTION Sends missing objects to remote repository, and updates the remote branch. +*NOTE*: This command is temporarily disabled if your cURL +library is older than 7.16, as the combination has been reported +not to work and sometimes corrupts repository. OPTIONS ------- diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index 841e8fac7f..51f1532ef7 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -38,10 +38,11 @@ OPTIONS The port number to bind the httpd to. (Default: 1234) -b|--browser:: - - The web browser command-line to execute to view the gitweb page. - If blank, the URL of the gitweb instance will be printed to - stdout. (Default: 'firefox') + The web browser that should be used to view the gitweb + page. This will be passed to the 'git-web--browse' helper + script along with the URL of the gitweb instance. See + linkgit:git-web--browse[1] for more information about this. If + the script fails, the URL will be printed to stdout. --start:: Start the httpd instance and exit. This does not generate @@ -72,7 +73,8 @@ You may specify configuration in your .git/config ----------------------------------------------------------------------- If the configuration variable 'instaweb.browser' is not set, -'web.browser' will be used instead if it is defined. +'web.browser' will be used instead if it is defined. See +linkgit:git-web--browse[1] for more information about this. Author ------ diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 5d816d0d8b..19ee017aed 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -8,7 +8,7 @@ git-merge-index - Run a merge for files needing merging SYNOPSIS -------- -'git-merge-index' [-o] [-q] <merge-program> (-a | \-- | <file>\*) +'git-merge-index' [-o] [-q] <merge-program> (-a | [--] <file>\*) DESCRIPTION ----------- diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 74cc7c1cb8..5c1bd3b081 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -99,7 +99,8 @@ base-name:: --max-pack-size=<n>:: Maximum size of each output packfile, expressed in MiB. If specified, multiple packfiles may be created. - The default is unlimited. + The default is unlimited, unless the config variable + `pack.packSizeLimit` is set. --incremental:: This flag causes an object already in a pack ignored @@ -176,6 +177,8 @@ base-name:: This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. + Specifying 0 will cause git to auto-detect the number of CPU's + and set the number of threads accordingly. --index-version=<version>[,<offset>]:: This is intended to be used by the test suite only. It allows diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 77fdaf146e..737894390d 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -15,6 +15,7 @@ DESCRIPTION ----------- Runs `git-fetch` with the given parameters, and calls `git-merge` to merge the retrieved head(s) into the current branch. +With `--rebase`, calls `git-rebase` instead of `git-merge`. Note that you can use `.` (current directory) as the <repository> to pull from the local repository -- this is useful @@ -25,6 +26,24 @@ OPTIONS ------- include::merge-options.txt[] +:git-pull: 1 + +\--rebase:: + Instead of a merge, perform a rebase after fetching. If + there is a remote ref for the upstream branch, and this branch + was rebased since last fetched, the rebase uses that information + to avoid rebasing non-local changes. To make this the default + for branch `<name>`, set configuration `branch.<name>.rebase` + to `true`. ++ +*NOTE:* This is a potentially _dangerous_ mode of operation. +It rewrites history, which does not bode well when you +published that history already. Do *not* use this option +unless you have read linkgit:git-rebase[1] carefully. + +\--no-rebase:: + Override earlier \--rebase. + include::fetch-options.txt[] include::pull-fetch-param.txt[] @@ -33,16 +52,6 @@ include::urls-remotes.txt[] include::merge-strategies.txt[] -\--rebase:: - Instead of a merge, perform a rebase after fetching. - *NOTE:* This is a potentially _dangerous_ mode of operation. - It rewrites history, which does not bode well when you - published that history already. Do *not* use this option - unless you have read linkgit:git-rebase[1] carefully. - -\--no-rebase:: - Override earlier \--rebase. - DEFAULT BEHAVIOUR ----------------- diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 5f2494495b..3128170bcd 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -47,9 +47,9 @@ even if it does not result in a fast forward update. + Note: If no explicit refspec is found, (that is neither on the command line nor in any Push line of the -corresponding remotes file---see below), then all the -heads that exist both on the local side and on the remote -side are updated. +corresponding remotes file---see below), then "matching" heads are +pushed: for every head that exists on the local side, the remote side is +updated if a head of the same name already exists on the remote side. + `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. + @@ -108,6 +108,55 @@ the remote repository. include::urls-remotes.txt[] +OUTPUT +------ + +The output of "git push" depends on the transport method used; this +section describes the output when pushing over the git protocol (either +locally or via ssh). + +The status of the push is output in tabular form, with each line +representing the status of a single ref. Each line is of the form: + +------------------------------- + <flag> <summary> <from> -> <to> (<reason>) +------------------------------- + +flag:: + A single character indicating the status of the ref. This is + blank for a successfully pushed ref, `!` for a ref that was + rejected or failed to push, and '=' for a ref that was up to + date and did not need pushing (note that the status of up to + date refs is shown only when `git push` is running verbosely). + +summary:: + For a successfully pushed ref, the summary shows the old and new + values of the ref in a form suitable for using as an argument to + `git log` (this is `<old>..<new>` in most cases, and + `<old>...<new>` for forced non-fast forward updates). For a + failed update, more details are given for the failure. + The string `rejected` indicates that git did not try to send the + ref at all (typically because it is not a fast forward). The + string `remote rejected` indicates that the remote end refused + the update; this rejection is typically caused by a hook on the + remote side. The string `remote failure` indicates that the + remote end did not report the successful update of the ref + (perhaps because of a temporary error on the remote side, a + break in the network connection, or other transient error). + +from:: + The name of the local ref being pushed, minus its + `refs/<type>/` prefix. In the case of deletion, the + name of the local ref is omitted. + +to:: + The name of the remote ref being updated, minus its + `refs/<type>/` prefix. + +reason:: + A human-readable explanation. In the case of successfully pushed + refs, no explanation is needed. For a failed ref, the reason for + failure is described. Examples -------- diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 10f6fa58bf..2cbd1f764b 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git-remote' -'git-remote' add [-t <branch>] [-m <branch>] [-f] [--mirror] <name> <url> +'git-remote' add [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url> 'git-remote' rm <name> 'git-remote' show <name> 'git-remote' prune <name> diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index a4e0a779de..fac59c9726 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -8,8 +8,8 @@ git-reset - Reset current HEAD to the specified state SYNOPSIS -------- [verse] -'git-reset' [--mixed | --soft | --hard] [-q] [<commit>] -'git-reset' [--mixed] [-q] [<commit>] [--] <paths>... +'git reset' [--mixed | --soft | --hard] [-q] [<commit>] +'git reset' [-q] [<commit>] [--] <paths>... DESCRIPTION ----------- @@ -37,7 +37,7 @@ OPTIONS --soft:: Does not touch the index file nor the working tree at all, but requires them to be in a good order. This leaves all your changed - files "Added but not yet committed", as linkgit:git-status[1] would + files "Changes to be committed", as linkgit:git-status[1] would put it. --hard:: @@ -176,6 +176,23 @@ $ git reset <3> committed as 'snapshot WIP'. This updates the index to show your WIP files as uncommitted. +Reset a single file in the index:: ++ +Suppose you have added a file to your index, but later decide you do not +want to add it to your commit. You can remove the file from the index +while keeping your changes with git reset. ++ +------------ +$ git reset -- frotz.c <1> +$ git commit -m "Commit files in index" <2> +$ git add frotz.c <3> +------------ ++ +<1> This removes the file from the index while keeping it in the working + directory. +<2> This commits all other changes in the index. +<3> Adds the file to the index again. + Author ------ Written by Junio C Hamano <junkio@cox.net> and Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 5b96eabfce..a8d489f9f2 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -31,6 +31,7 @@ SYNOPSIS [ \--(author|committer|grep)=<pattern> ] [ \--regexp-ignore-case | \-i ] [ \--extended-regexp | \-E ] + [ \--fixed-strings | \-F ] [ \--date={local|relative|default|iso|rfc|short} ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 5d9c36985f..f02f6bbb49 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -229,13 +229,13 @@ blobs contained in a commit. * A colon, optionally followed by a stage number (0 to 3) and a colon, followed by a path; this names a blob object in the index at the given path. Missing stage number (and the colon - that follows it) names an stage 0 entry. During a merge, stage + that follows it) names a stage 0 entry. During a merge, stage 1 is the common ancestor, stage 2 is the target branch's version (typically the current branch), and stage 3 is the version from the branch being merged. -Here is an illustration, by Jon Loeliger. Both node B and C are -a commit parents of commit node A. Parent commits are ordered +Here is an illustration, by Jon Loeliger. Both commit nodes B +and C are parents of commit node A. Parent commits are ordered left-to-right. G H I J @@ -291,7 +291,7 @@ and its parent commits exists. `r1{caret}@` notation means all parents of `r1`. `r1{caret}!` includes commit `r1` but excludes its all parents. -Here are a handful examples: +Here are a handful of examples: D G H D D F G H I J D F diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 4b8ec8a200..336d797e80 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -96,11 +96,40 @@ The --cc option must be repeated for each user you want on the cc list. servers typically listen to smtp port 25 and ssmtp port 465). ---smtp-user, --smtp-pass:: - Username and password for SMTP-AUTH. Defaults are the values of - the configuration values 'sendemail.smtpuser' and - 'sendemail.smtppass', but see also 'sendemail.identity'. - If not set, authentication is not attempted. +--smtp-user:: + Username for SMTP-AUTH. In place of this option, the following + configuration variables can be specified: ++ +-- + * sendemail.smtpuser + * sendemail.<identity>.smtpuser (see sendemail.identity). +-- ++ +However, --smtp-user always overrides these variables. ++ +If a username is not specified (with --smtp-user or a +configuration variable), then authentication is not attempted. + +--smtp-pass:: + Password for SMTP-AUTH. The argument is optional: If no + argument is specified, then the empty string is used as + the password. ++ +In place of this option, the following configuration variables +can be specified: ++ +-- + * sendemail.smtppass + * sendemail.<identity>.smtppass (see sendemail.identity). +-- ++ +However, --smtp-pass always overrides these variables. ++ +Furthermore, passwords need not be specified in configuration files +or on the command line. If a username has been specified (with +--smtp-user or a configuration variable), but no password has been +specified (with --smtp-pass or a configuration variable), then the +user is prompted for a password while the input is masked for privacy. --smtp-ssl:: If set, connects to the SMTP server using SSL. @@ -117,6 +146,17 @@ The --cc option must be repeated for each user you want on the cc list. Default is the value of 'sendemail.suppressfrom' configuration value; if that is unspecified, default to --no-suppress-from. +--suppress-cc:: + Specify an additional category of recipients to suppress the + auto-cc of. 'self' will avoid including the sender, 'author' will + avoid including the patch author, 'cc' will avoid including anyone + mentioned in Cc lines in the patch, 'sob' will avoid including + anyone mentioned in Signed-off-by lines, and 'cccmd' will avoid + running the --cc-cmd. 'all' will suppress all auto cc values. + Default is the value of 'sendemail.suppresscc' configuration value; + if that is unspecified, default to 'self' if --suppress-from is + specified, as well as 'sob' if --no-signed-off-cc is specified. + --thread, --no-thread:: If this is set, the In-Reply-To header will be set on each email sent. If disabled with "--no-thread", no emails will have the In-Reply-To @@ -137,6 +177,8 @@ The --cc option must be repeated for each user you want on the cc list. Specify the primary recipient of the emails generated. Generally, this will be the upstream maintainer of the project involved. + Default is the value of the 'sendemail.to' configuration value; + if that is unspecified, this will be prompted for. + The --to option must be repeated for each user you want on the to list. diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 9889806a5e..48e6f5a3f7 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git-stash' (list | show [<stash>] | apply [<stash>] | clear) -'git-stash' [save] [message...] +'git-stash' [save [<message>]] DESCRIPTION ----------- @@ -36,13 +36,14 @@ is also possible). OPTIONS ------- -save:: +save [<message>]:: Save your local modifications to a new 'stash', and run `git-reset --hard` to revert them. This is the default action when no - subcommand is given. + subcommand is given. The <message> part is optional and gives + the description along with the stashed state. -list:: +list [<options>]:: List the stashes that you currently have. Each 'stash' is listed with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1}` is @@ -54,6 +55,9 @@ list:: stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation stash@{1}: On master: 9cc0589... Add git-stash ---------------------------------------------------------------- ++ +The command takes options applicable to the linkgit:git-log[1] +command to control what is shown and how. show [<stash>]:: diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index cffc6d48fb..e818e6e789 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,8 +9,9 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git-submodule' [--quiet] [-b branch] add <repository> [<path>] -'git-submodule' [--quiet] [--cached] [status|init|update] [--] [<path>...] +'git-submodule' [--quiet] add [-b branch] [--] <repository> [<path>] +'git-submodule' [--quiet] status [--cached] [--] [<path>...] +'git-submodule' [--quiet] [init|update] [--] [<path>...] COMMANDS diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index e1a1d46a9f..340f1be02a 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -161,6 +161,13 @@ New features: + Any other arguments are passed directly to `git log' +'blame':: + Show what revision and author last modified each line of a file. This is + identical to `git blame', but SVN revision numbers are shown instead of git + commit hashes. ++ +All arguments are passed directly to `git blame'. + -- 'find-rev':: When given an SVN revision number of the form 'rN', returns the @@ -456,10 +463,13 @@ have each person clone that repository with 'git clone': ------------------------------------------------------------------------ # Do the initial import on a server ssh server "cd /pub && git-svn clone http://svn.foo.org/project -# Clone locally - git clone server:/pub/project -# Tell git-svn which branch contains the Subversion commits - git update-ref refs/remotes/git-svn origin/master +# Clone locally - make sure the refs/remotes/ space matches the server + mkdir project + cd project + git-init + git remote add origin server:/pub/project + git config --add remote.origin.fetch=+refs/remotes/*:refs/remotes/* + git fetch # Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server) git-svn init http://svn.foo.org/project # Pull the latest changes from Subversion diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt new file mode 100644 index 0000000000..df57d010e5 --- /dev/null +++ b/Documentation/git-web--browse.txt @@ -0,0 +1,78 @@ +git-web--browse(1) +================== + +NAME +---- +git-web--browse - git helper script to launch a web browser + +SYNOPSIS +-------- +'git-web--browse' [OPTIONS] URL/FILE ... + +DESCRIPTION +----------- + +This script tries, as much as possible, to display the URLs and FILEs +that are passed as arguments, as HTML pages in new tabs on an already +opened web browser. + +The following browsers (or commands) are currently supported: + +* firefox (this is the default under X Window when not using KDE) +* iceweasel +* konqueror (this is the default under KDE) +* w3m (this is the default outside graphical environments) +* links +* lynx +* dillo +* open (this is the default under Mac OS X GUI) + +OPTIONS +------- +-b BROWSER|--browser=BROWSER:: + Use the specified BROWSER. It must be in the list of supported + browsers. + +-t BROWSER|--tool=BROWSER:: + Same as above. + +-c CONF.VAR|--config=CONF.VAR:: + CONF.VAR is looked up in the git config files. If it's set, + then its value specify the browser that should be used. + +CONFIGURATION VARIABLES +----------------------- + +The web browser can be specified using a configuration variable passed +with the -c (or --config) command line option, or the 'web.browser' +configuration variable if the former is not used. + +You can explicitly provide a full path to your preferred browser by +setting the configuration variable 'browser.<tool>.path'. For example, +you can configure the absolute path to firefox by setting +'browser.firefox.path'. Otherwise, 'git-web--browse' assumes the tool +is available in PATH. + +Note that these configuration variables should probably be set using +the '--global' flag, for example like this: + +------------------------------------------------ +$ git config --global web.browser firefox +------------------------------------------------ + +as they are probably more user specific than repository specific. +See linkgit:git-config[1] for more information about this. + +Author +------ +Written by Christian Couder <chriscool@tuxfamily.org> and the git-list +<git@vger.kernel.org>, based on git-mergetool by Theodore Y. Ts'o. + +Documentation +------------- +Documentation by Christian Couder <chriscool@tuxfamily.org> and the +git-list <git@vger.kernel.org>. + +GIT +--- +Part of the linkgit:git[7] suite diff --git a/Documentation/git.txt b/Documentation/git.txt index 4ece40d1eb..741ae0e4c8 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,6 +43,14 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: +* link:v1.5.4.3/git.html[documentation for release 1.5.4.3] + +* release notes for + link:RelNotes-1.5.4.3.txt[1.5.4.3], + link:RelNotes-1.5.4.2.txt[1.5.4.2], + link:RelNotes-1.5.4.1.txt[1.5.4.1], + link:RelNotes-1.5.4.txt[1.5.4]. + * link:v1.5.3.8/git.html[documentation for release 1.5.3.8] * release notes for diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 35a29fd60c..84ec9623a2 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -133,6 +133,26 @@ When `core.autocrlf` is set to "input", line endings are converted to LF upon checkin, but there is no conversion done upon checkout. +If `core.safecrlf` is set to "true" or "warn", git verifies if +the conversion is reversible for the current setting of +`core.autocrlf`. For "true", git rejects irreversible +conversions; for "warn", git only prints a warning but accepts +an irreversible conversion. The safety triggers to prevent such +a conversion done to the files in the work tree, but there are a +few exceptions. Even though... + +- "git add" itself does not touch the files in the work tree, the + next checkout would, so the safety triggers; + +- "git apply" to update a text file with a patch does touch the files + in the work tree, but the operation is about text files and CRLF + conversion is about fixing the line ending inconsistencies, so the + safety does not trigger; + +- "git diff" itself does not touch the files in the work tree, it is + often run to inspect the changes you intend to next "git add". To + catch potential problems early, safety triggers. + `ident` ^^^^^^^ diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index 08373f52bb..e847b3ba63 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -57,6 +57,13 @@ Patterns have the following format: included again. If a negated pattern matches, this will override lower precedence patterns sources. + - If the pattern ends with a slash, it is removed for the + purpose of the following description, but it would only find + a match with a directory. In other words, `foo/` will match a + directory `foo` and paths underneath it, but will not match a + regular file or a symbolic link `foo` (this is consistent + with the way how pathspec works in general in git). + - If the pattern does not contain a slash '/', git treats it as a shell glob pattern and checks for a match against the pathname without leading directories. diff --git a/Documentation/hooks.txt b/Documentation/hooks.txt index f110162b01..76b8d77460 100644 --- a/Documentation/hooks.txt +++ b/Documentation/hooks.txt @@ -61,6 +61,35 @@ The default 'pre-commit' hook, when enabled, catches introduction of lines with trailing whitespaces and aborts the commit when such a line is found. +All the `git-commit` hooks are invoked with the environment +variable `GIT_EDITOR=:` if the command will not bring up an editor +to modify the commit message. + +prepare-commit-msg +------------------ + +This hook is invoked by `git-commit` right after preparing the +default log message, and before the editor is started. + +It takes one to three parameters. The first is the name of the file +that the commit log message. The second is the source of the commit +message, and can be: `message` (if a `\-m` or `\-F` option was +given); `template` (if a `\-t` option was given or the +configuration option `commit.template` is set); `merge` (if the +commit is a merge or a `.git/MERGE_MSG` file exists); `squash` +(if a `.git/SQUASH_MSG` file exists); or `commit`, followed by +a commit SHA1 (if a `\-c`, `\-C` or `\--amend` option was given). + +If the exit status is non-zero, `git-commit` will abort. + +The purpose of the hook is to edit the message file in place, and +it is not suppressed by the `\--no-verify` option. A non-zero exit +means a failure of the hook and aborts the commit. It should not +be used as replacement for pre-commit hook. + +The sample `prepare-commit-msg` hook that comes with git comments +out the `Conflicts:` part of a merge's commit message. + commit-msg ---------- diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl new file mode 100644 index 0000000000..fe3cd72d6f --- /dev/null +++ b/Documentation/manpage-1.72.xsl @@ -0,0 +1,17 @@ +<!-- callout.xsl: converts asciidoc callouts to man page format --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> +<xsl:template match="co"> + <xsl:value-of select="concat('▓fB(',substring-after(@id,'-'),')▓fR')"/> +</xsl:template> +<xsl:template match="calloutlist"> + <xsl:text>⌂sp </xsl:text> + <xsl:apply-templates/> + <xsl:text> </xsl:text> +</xsl:template> +<xsl:template match="callout"> + <xsl:value-of select="concat('▓fB',substring-after(@arearefs,'-'),'. ▓fR')"/> + <xsl:apply-templates/> + <xsl:text>⌂br </xsl:text> +</xsl:template> + +</xsl:stylesheet> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index a8138e27a1..259072c078 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -153,6 +153,11 @@ limiting may be applied. Consider the limiting patterns to be extended regular expressions instead of the default basic regular expressions. +-F, --fixed-strings:: + + Consider the limiting patterns to be fixed strings (don't interpret + pattern as a regular expression). + --remove-empty:: Stop when a given path disappears from the tree. diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt new file mode 100644 index 0000000000..073b22bd83 --- /dev/null +++ b/Documentation/technical/api-remote.txt @@ -0,0 +1,123 @@ +Remotes configuration API +========================= + +The API in remote.h gives access to the configuration related to +remotes. It handles all three configuration mechanisms historically +and currently used by git, and presents the information in a uniform +fashion. Note that the code also handles plain URLs without any +configuration, giving them just the default information. + +struct remote +------------- + +`name`:: + + The user's nickname for the remote + +`url`:: + + An array of all of the url_nr URLs configured for the remote + +`push`:: + + An array of refspecs configured for pushing, with + push_refspec being the literal strings, and push_refspec_nr + being the quantity. + +`fetch`:: + + An array of refspecs configured for fetching, with + fetch_refspec being the literal strings, and fetch_refspec_nr + being the quantity. + +`fetch_tags`:: + + The setting for whether to fetch tags (as a separate rule from + the configured refspecs); -1 means never to fetch tags, 0 + means to auto-follow tags based on the default heuristic, 1 + means to always auto-follow tags, and 2 means to fetch all + tags. + +`receivepack`, `uploadpack`:: + + The configured helper programs to run on the remote side, for + git-native protocols. + +`http_proxy`:: + + The proxy to use for curl (http, https, ftp, etc.) URLs. + +struct remotes can be found by name with remote_get(), and iterated +through with for_each_remote(). remote_get(NULL) will return the +default remote, given the current branch and configuration. + +struct refspec +-------------- + +A struct refspec holds the parsed interpretation of a refspec. If it +will force updates (starts with a '+'), force is true. If it is a +pattern (sides end with '*') pattern is true. src and dest are the two +sides (if a pattern, only the part outside of the wildcards); if there +is only one side, it is src, and dst is NULL; if sides exist but are +empty (i.e., the refspec either starts or ends with ':'), the +corresponding side is "". + +This parsing can be done to an array of strings to give an array of +struct refpsecs with parse_ref_spec(). + +remote_find_tracking(), given a remote and a struct refspec with +either src or dst filled out, will fill out the other such that the +result is in the "fetch" specification for the remote (note that this +evaluates patterns and returns a single result). + +struct branch +------------- + +Note that this may end up moving to branch.h + +struct branch holds the configuration for a branch. It can be looked +up with branch_get(name) for "refs/heads/{name}", or with +branch_get(NULL) for HEAD. + +It contains: + +`name`:: + + The short name of the branch. + +`refname`:: + + The full path for the branch ref. + +`remote_name`:: + + The name of the remote listed in the configuration. + +`remote`:: + + The struct remote for that remote. + +`merge_name`:: + + An array of the "merge" lines in the configuration. + +`merge`:: + + An array of the struct refspecs used for the merge lines. That + is, merge[i]->dst is a local tracking ref which should be + merged into this branch by default. + +`merge_nr`:: + + The number of merge configurations + +branch_has_merge_config() returns true if the given branch has merge +configuration given. + +Other stuff +----------- + +There is other stuff in remote.h that is related, in general, to the +process of interacting with remotes. + +(Daniel Barkalow) diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index 19d2f64f73..dfbf9ac5d0 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -1,10 +1,171 @@ run-command API =============== -Talk about <run-command.h>, and things like: +The run-command API offers a versatile tool to run sub-processes with +redirected input and output as well as with a modified environment +and an alternate current directory. -* Environment the command runs with (e.g. GIT_DIR); -* File descriptors and pipes; -* Exit status; +A similar API offers the capability to run a function asynchronously, +which is primarily used to capture the output that the function +produces in the caller in order to process it. -(Hannes, Dscho, Shawn) + +Functions +--------- + +`start_command`:: + + Start a sub-process. Takes a pointer to a `struct child_process` + that specifies the details and returns pipe FDs (if requested). + See below for details. + +`finish_command`:: + + Wait for the completion of a sub-process that was started with + start_command(). + +`run_command`:: + + A convenience function that encapsulates a sequence of + start_command() followed by finish_command(). Takes a pointer + to a `struct child_process` that specifies the details. + +`run_command_v_opt`, `run_command_v_opt_dir`, `run_command_v_opt_cd_env`:: + + Convenience functions that encapsulate a sequence of + start_command() followed by finish_command(). The argument argv + specifies the program and its arguments. The argument opt is zero + or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, or + `RUN_COMMAND_STDOUT_TO_STDERR` that correspond to the members + .no_stdin, .git_cmd, .stdout_to_stderr of `struct child_process`. + The argument dir corresponds the member .dir. The argument env + corresponds to the member .env. + +`start_async`:: + + Run a function asynchronously. Takes a pointer to a `struct + async` that specifies the details and returns a pipe FD + from which the caller reads. See below for details. + +`finish_async`:: + + Wait for the completeion of an asynchronous function that was + started with start_async(). + + +Data structures +--------------- + +* `struct child_process` + +This describes the arguments, redirections, and environment of a +command to run in a sub-process. + +The caller: + +1. allocates and clears (memset(&chld, '0', sizeof(chld));) a + struct child_process variable; +2. initializes the members; +3. calls start_command(); +4. processes the data; +5. closes file descriptors (if necessary; see below); +6. calls finish_command(). + +The .argv member is set up as an array of string pointers (NULL +terminated), of which .argv[0] is the program name to run (usually +without a path). If the command to run is a git command, set argv[0] to +the command name without the 'git-' prefix and set .git_cmd = 1. + +The members .in, .out, .err are used to redirect stdin, stdout, +stderr as follows: + +. Specify 0 to request no special redirection. No new file descriptor + is allocated. The child process simply inherits the channel from the + parent. + +. Specify -1 to have a pipe allocated; start_command() replaces -1 + by the pipe FD in the following way: + + .in: Returns the writable pipe end into which the caller writes; + the readable end of the pipe becomes the child's stdin. + + .out, .err: Returns the readable pipe end from which the caller + reads; the writable end of the pipe end becomes child's + stdout/stderr. + + The caller of start_command() must close the so returned FDs + after it has completed reading from/writing to it! + +. Specify a file descriptor > 0 to be used by the child: + + .in: The FD must be readable; it becomes child's stdin. + .out: The FD must be writable; it becomes child's stdout. + .err > 0 is not supported. + + The specified FD is closed by start_command(), even if it fails to + run the sub-process! + +. Special forms of redirection are available by setting these members + to 1: + + .no_stdin, .no_stdout, .no_stderr: The respective channel is + redirected to /dev/null. + + .stdout_to_stderr: stdout of the child is redirected to the + parent's stderr (i.e. *not* to what .err or + .no_stderr specify). + +To modify the environment of the sub-process, specify an array of +string pointers (NULL terminated) in .env: + +. If the string is of the form "VAR=value", i.e. it contains '=' + the variable is added to the child process's environment. + +. If the string does not contain '=', it names an environement + variable that will be removed from the child process's envionment. + +To specify a new initial working directory for the sub-process, +specify it in the .dir member. + + +* `struct async` + +This describes a function to run asynchronously, whose purpose is +to produce output that the caller reads. + +The caller: + +1. allocates and clears (memset(&asy, '0', sizeof(asy));) a + struct async variable; +2. initializes .proc and .data; +3. calls start_async(); +4. processes the data by reading from the fd in .out; +5. closes .out; +6. calls finish_async(). + +The function pointer in .proc has the following signature: + + int proc(int fd, void *data); + +. fd specifies a writable file descriptor to which the function must + write the data that it produces. The function *must* close this + descriptor before it returns. + +. data is the value that the caller has specified in the .data member + of struct async. + +. The return value of the function is 0 on success and non-zero + on failure. If the function indicates failure, finish_async() will + report failure as well. + + +There are serious restrictions on what the asynchronous function can do +because this facility is implemented by a pipe to a forked process on +UNIX, but by a thread in the same address space on Windows: + +. It cannot change the program's state (global variables, environment, + etc.) in a way that the caller notices; in other words, .out is the + only communication channel to the caller. + +. It must not change the program's state that the caller of the + facility also uses. diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index 5030d9f2f8..6bdf034b3a 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -184,7 +184,7 @@ In a large project where raciness avoidance cost really matters, however, the initial computation of all object names in the index takes more than one second, and the index file is written out after all that happens. Therefore the timestamp of the -index file will be more than one seconds later than the the +index file will be more than one seconds later than the youngest file in the working tree. This means that in these cases there actually will not be any racily clean entry in the resulting index. diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 81ac17f32a..fa34c67471 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -44,3 +44,26 @@ endif::git-clone[] ifdef::git-clone[] They are equivalent, except the former implies --local option. endif::git-clone[] + + +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 +use will be rewritten into URLs that work), you can create a +configuration section of the form: + +------------ + [url "<actual url base>"] + insteadOf = <other url base> +------------ + +For example, with this: + +------------ + [url "git://git.host.xz/"] + insteadOf = host.xz:/path/to/ + insteadOf = work: +------------ + +a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be +rewritten in any context that takes a URL to be "git://git.host.xz/repo.git". + |