path: root/Documentation
diff options
Diffstat (limited to 'Documentation')
22 files changed, 795 insertions, 59 deletions
diff --git a/Documentation/.gitattributes b/Documentation/.gitattributes
new file mode 100644
index 0000000..ddb0301
--- /dev/null
+++ b/Documentation/.gitattributes
@@ -0,0 +1 @@
+*.txt whitespace
diff --git a/Documentation/RelNotes-1.5.5.txt b/Documentation/RelNotes-1.5.5.txt
new file mode 100644
index 0000000..c8b4f72
--- /dev/null
+++ b/Documentation/RelNotes-1.5.5.txt
@@ -0,0 +1,78 @@
+GIT v1.5.5 Release Notes
+Updates since v1.5.4
+ * 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.
+ * 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
+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 de08d09..0e155c9 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 ( and the
- maintainer ( If you use
- git-send-email(1), please test it first by sending
- email to yourself.
+ maintainer ( 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
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/config.txt b/Documentation/config.txt
index 6d8cca4..7b67671 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.
+ 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
+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`
If false, symbolic links are checked out as small plain files that
contain the link text. linkgit:git-update-index[1] and
@@ -444,6 +489,13 @@ color.status.<slot>::
Specify a file to use as the template for new commit messages.
+ 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.
When using `git diff` to compare with work tree
files, do not consider stat-only change as changed.
@@ -766,6 +818,12 @@ pack.indexVersion::
whenever the corresponding pack is larger than 2 GB. Otherwise
the default is 1.
+ 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].
The default merge strategy to use when pulling multiple branches
at once.
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index c3725b2..b4ae61f 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -280,8 +280,8 @@ order).
-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
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index 0742152..1c3dfb4 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -51,6 +51,10 @@ OPTIONS
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).
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index bd625ab..96f6767 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
+ M 644 inline .gitignore
+ data <<EOF
+ .gitignore
+ M 777 inline bob
+ $ 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 :
+ -------------------
Tips and Tricks
The following tips and tricks have been collected from various
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index f3cb24f..71a7335 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -75,9 +75,11 @@ OPTIONS
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 fb77ca3..0926dc1 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -47,27 +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.
-The following browsers are currently supported by 'git-help--browse':
-* 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 X Window)
-* links
-* lynx
-* dillo
+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.
@@ -84,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-instaweb.txt b/Documentation/git-instaweb.txt
index 841e8fa..51f1532 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)
- 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 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.
diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt
index 5d816d0..19ee017 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
-'git-merge-index' [-o] [-q] <merge-program> (-a | \-- | <file>\*)
+'git-merge-index' [-o] [-q] <merge-program> (-a | [--] <file>\*)
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index 74cc7c1..8353be1 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -99,7 +99,8 @@ base-name::
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.
This flag causes an object already in a pack ignored
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 179bdfc..7378943 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
@@ -26,19 +27,14 @@ OPTIONS
:git-pull: 1
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 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
@@ -48,6 +44,14 @@ unless you have read linkgit:git-rebase[1] carefully.
Override earlier \--rebase.
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 0554f2b..336d797 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
---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.
+ 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.
+ 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.
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.
+ 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
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index b1d527f..340f1be 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'
+ 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'.
When given an SVN revision number of the form 'rN', returns the
diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt
new file mode 100644
index 0000000..df57d01
--- /dev/null
+++ b/Documentation/git-web--browse.txt
@@ -0,0 +1,78 @@
+git-web--browse - git helper script to launch a web browser
+'git-web--browse' [OPTIONS] URL/FILE ...
+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)
+-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.
+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.
+Written by Christian Couder <> and the git-list
+<>, based on git-mergetool by Theodore Y. Ts'o.
+Documentation by Christian Couder <> and the
+git-list <>.
+Part of the linkgit:git[7] suite
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 17aee93..741ae0e 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -43,9 +43,12 @@ 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/git.html[documentation for release 1.5.4]
+* link:v1.5.4.3/git.html[documentation for release]
* release notes for
+ link:RelNotes-[],
+ link:RelNotes-[],
+ link:RelNotes-[],
* link:v1.5.3.8/git.html[documentation for release]
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 35a29fd..84ec962 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.
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 08373f5..e847b3b 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 f110162..76b8d77 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.
+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.
diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt
new file mode 100644
index 0000000..073b22b
--- /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
+ The user's nickname for the remote
+ An array of all of the url_nr URLs configured for the remote
+ An array of refspecs configured for pushing, with
+ push_refspec being the literal strings, and push_refspec_nr
+ being the quantity.
+ An array of refspecs configured for fetching, with
+ fetch_refspec being the literal strings, and fetch_refspec_nr
+ being the quantity.
+ 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.
+ 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:
+ The short name of the branch.
+ The full path for the branch ref.
+ The name of the remote listed in the configuration.
+ The struct remote for that remote.
+ An array of the "merge" lines in the configuration.
+ 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.
+ 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 19d2f64..dfbf9ac 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)
+ 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.
+ Wait for the completion of a sub-process that was started with
+ start_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.
+ 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.
+ 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.