summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/.gitattributes1
-rw-r--r--Documentation/RelNotes-1.5.4.1.txt17
-rw-r--r--Documentation/RelNotes-1.5.4.2.txt43
-rw-r--r--Documentation/RelNotes-1.5.4.3.txt27
-rw-r--r--Documentation/RelNotes-1.5.5.txt78
-rw-r--r--Documentation/SubmittingPatches65
-rw-r--r--Documentation/blame-options.txt2
-rw-r--r--Documentation/config.txt60
-rw-r--r--Documentation/git-add.txt4
-rw-r--r--Documentation/git-branch.txt15
-rw-r--r--Documentation/git-checkout.txt7
-rw-r--r--Documentation/git-clone.txt13
-rw-r--r--Documentation/git-commit.txt4
-rw-r--r--Documentation/git-cvsimport.txt4
-rw-r--r--Documentation/git-describe.txt4
-rw-r--r--Documentation/git-fast-import.txt87
-rw-r--r--Documentation/git-grep.txt4
-rw-r--r--Documentation/git-help.txt26
-rw-r--r--Documentation/git-instaweb.txt12
-rw-r--r--Documentation/git-merge-index.txt2
-rw-r--r--Documentation/git-pack-objects.txt3
-rw-r--r--Documentation/git-pull.txt30
-rw-r--r--Documentation/git-push.txt55
-rw-r--r--Documentation/git-reset.txt23
-rw-r--r--Documentation/git-send-email.txt50
-rw-r--r--Documentation/git-stash.txt5
-rw-r--r--Documentation/git-svn.txt7
-rw-r--r--Documentation/git-web--browse.txt78
-rw-r--r--Documentation/git.txt5
-rw-r--r--Documentation/gitattributes.txt20
-rw-r--r--Documentation/gitignore.txt7
-rw-r--r--Documentation/hooks.txt29
-rw-r--r--Documentation/technical/api-remote.txt123
-rw-r--r--Documentation/technical/api-run-command.txt171
34 files changed, 988 insertions, 93 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.4.1.txt b/Documentation/RelNotes-1.5.4.1.txt
new file mode 100644
index 0000000..d4e44b8
--- /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 0000000..21d0df5
--- /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 0000000..b0fc67f
--- /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.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
+--------------------
+
+(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 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 (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 ea1007b..c11bb7d 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 44cb640..fb6dae0 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
@@ -337,7 +382,7 @@ branch.autosetupmerge::
so that linkgit:git-pull[1] will appropriately merge from that
remote branch. Note that even if this option is not set,
this behavior can be chosen per-branch using the `--track`
- and `--no-track` options. This option defaults to false.
+ and `--no-track` options. This option defaults to true.
branch.<name>.remote::
When in branch <name>, it tells `git fetch` which remote to fetch.
@@ -448,6 +493,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.
@@ -770,6 +822,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.
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 9d2ac86..4779909 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-branch.txt b/Documentation/git-branch.txt
index f920c04..7e8874a 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -34,11 +34,11 @@ Note that this will create the new branch, but it will not switch the
working tree to it; use "git checkout <newbranch>" to switch to the
new branch.
-When a local branch is started off a remote branch, git can setup the
+When a local branch is started off a remote branch, git sets up the
branch so that linkgit:git-pull[1] will appropriately merge from that
-remote branch. If this behavior is desired, it is possible to make it
-the default using the global `branch.autosetupmerge` configuration
-flag. Otherwise, it can be chosen per-branch using the `--track`
+remote branch. If this behavior is not desired, it is possible to
+disable it using the global `branch.autosetupmerge` configuration
+flag. That setting can be overridden by using the `--track`
and `--no-track` options.
With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
@@ -108,10 +108,11 @@ OPTIONS
Set up configuration so that git-pull will automatically
retrieve data from the remote branch. Use this if you always
pull from the same remote branch into the new branch, or if you
- don't want to use "git pull <repository> <refspec>" explicitly. Set the
- branch.autosetupmerge configuration variable to true if you
+ don't want to use "git pull <repository> <refspec>" explicitly.
+ This behavior is the default. Set the
+ branch.autosetupmerge configuration variable to false if you
want git-checkout and git-branch to always behave as if
- '--track' were given.
+ '--no-track' were given.
--no-track::
When a branch is created off a remote branch,
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 584359f..b4cfa04 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -52,10 +52,11 @@ OPTIONS
set up configuration so that git-pull will automatically
retrieve data from the remote branch. Use this if you always
pull from the same remote branch into the new branch, or if you
- don't want to use "git pull <repository> <refspec>" explicitly. Set the
- branch.autosetupmerge configuration variable to true if you
+ don't want to use "git pull <repository> <refspec>" explicitly.
+ This behavior is the default. Set the
+ branch.autosetupmerge configuration variable to false if you
want git-checkout and git-branch to always behave as if
- '--track' were given.
+ '--no-track' were given.
--no-track::
When -b is given and a branch is created off a remote branch,
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 2341881..9758243 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -62,12 +62,13 @@ 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.
++
+*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.
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).
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-cvsimport.txt b/Documentation/git-cvsimport.txt
index dbce503..6f91b9e 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-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).
+
EXAMPLES
--------
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
+ 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-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
-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 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.
CONFIGURATION VARIABLES
-----------------------
@@ -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)
-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 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
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 74cc7c1..8353be1 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
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 4cc633a..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,28 +27,31 @@ OPTIONS
include::merge-options.txt[]
:git-pull: 1
-include::fetch-options.txt[]
-
-include::pull-fetch-param.txt[]
-
-include::urls-remotes.txt[]
-
-include::merge-strategies.txt[]
\--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.
-
- *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.
+ 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[]
+
+include::urls-remotes.txt[]
+
+include::merge-strategies.txt[]
+
DEFAULT BEHAVIOUR
-----------------
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 5f24944..3128170 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-reset.txt b/Documentation/git-reset.txt
index a4e0a77..fac59c9 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-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
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
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index cd0dc1b..48e6f5a 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -43,7 +43,7 @@ save [<message>]::
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
@@ -55,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-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'
+'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
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(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 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 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]
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.
+
`ident`
^^^^^^^
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.
+
+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/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
+-------------
+
+`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 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)
+
+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.