summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/RelNotes-1.6.1.txt120
-rw-r--r--Documentation/SubmittingPatches2
-rw-r--r--Documentation/config.txt4
-rw-r--r--Documentation/diff-options.txt6
-rw-r--r--Documentation/git-checkout.txt17
-rw-r--r--Documentation/git-commit.txt6
-rw-r--r--Documentation/git-count-objects.txt5
-rw-r--r--Documentation/git-daemon.txt9
-rw-r--r--Documentation/git-diff-tree.txt19
-rw-r--r--Documentation/git-hash-object.txt20
-rw-r--r--Documentation/git-help.txt4
-rw-r--r--Documentation/git-imap-send.txt78
-rw-r--r--Documentation/git-merge-base.txt77
-rw-r--r--Documentation/git-merge.txt24
-rw-r--r--Documentation/git-submodule.txt26
-rw-r--r--Documentation/gitattributes.txt6
-rw-r--r--Documentation/rev-list-options.txt42
17 files changed, 418 insertions, 47 deletions
diff --git a/Documentation/RelNotes-1.6.1.txt b/Documentation/RelNotes-1.6.1.txt
new file mode 100644
index 0000000000..609d4ca562
--- /dev/null
+++ b/Documentation/RelNotes-1.6.1.txt
@@ -0,0 +1,120 @@
+GIT v1.6.1 Release Notes
+========================
+
+Updates since v1.6.0
+--------------------
+
+When some commands (e.g. "git log", "git diff") spawn pager internally, we
+used to make the pager the parent process of the git command that produces
+output. This meant that the exit status of the whole thing comes from the
+pager, not the underlying git command. We swapped the order of the
+processes around and you will see the exit code from the command from now
+on.
+
+(subsystems)
+
+* gitk can call out to git-gui to view "git blame" output; git-gui in turn
+ can run gitk from its blame view.
+
+(portability)
+
+* ...
+
+(documentation)
+
+* ...
+
+(performance)
+
+* The underlying diff machinery to produce textual output has been
+ optimized, which would result in faster "git blame" processing.
+
+* Most of the test scripts (but not the ones that try to run servers)
+ can be run in parallel.
+
+(usability, bells and whistles)
+
+* "git checkout --track origin/hack" used to be a syntax error. It now
+ DWIMs to create a corresponding local branch "hack", i.e. acts as if you
+ said "git checkout --track -b hack origin/hack".
+
+* "git cherry-pick" can also utilize rerere for conflict resolution.
+
+* "git commit --author=$name" can look up author name from existing
+ commits.
+
+* "git count-objects" reports the on-disk footprint for packfiles and
+ their corresponding idx files.
+
+* "git daemon" learned --max-connections=<count> option.
+
+* "git diff" learned to mimick --suppress-blank-empty from GNU diff via a
+ configuration option.
+
+* "git diff" learned to put more sensible hunk headers for Python and
+ HTML contents.
+
+* "git help" learned to use GIT_MAN_VIEWER environment variable before
+ using "man" program.
+
+* "git imap-send" can optionally talk SSL.
+
+* "git index-pack" is more careful against disk corruption while
+ completing a thin pack.
+
+* "git log --check" and "git log --exit-code" passes their underlying diff
+ status with their exit status code.
+
+* "git log" learned --simplify-merges, a milder variant of --full-history;
+ "gitk --simplify-merges" is easier to view than with --full-history.
+
+* "git merge --squash" and "git merge --no-ff" into an unborn branch are
+ noticed as user errors.
+
+* "git merge -s $strategy" can use a custom built strategy if you have a
+ command "git-merge-$strategy" on your $PATH.
+
+* "git reflog expire branch" can be used in place of "git reflog expire
+ refs/heads/branch".
+
+* "git submodule foreach" subcommand allows you to iterate over checked
+ out submodules.
+
+* "git submodule sync" subcommands allows you to update the origin URL
+ recorded in submodule directories from the toplevel .gitmodules file.
+
+(internal)
+
+* "git hash-object" learned to lie about the path being hashed, so that
+ correct gitattributes processing can be done while hashing contents
+ stored in a temporary file.
+
+Fixes since v1.6.0
+------------------
+
+All of the fixes in v1.6.0.X maintenance series are included in this
+release, unless otherwise noted.
+
+* "git add" and "git update-index" incorrectly allowed adding S/F when S
+ is a tracked symlink that points at a directory D that has a path F in
+ it (we still need to fix a similar nonsense when S is a submodule and F
+ is a path in it).
+
+* "git diff --stdin" used to take two trees on a line and compared them,
+ but we droppped support for such a use case long time ago. This has
+ been resurrected.
+
+* "git filter-branch" failed to rewrite a tag name with slashes in it.
+
+* "git push --tags --all $there" failed with generic usage message without
+ telling saying these two options are incompatible.
+
+* "git log --author/--committer" match used to potentially match the
+ timestamp part, exposing internal implementation detail. Also these did
+ not work with --fixed-strings match at all.
+
+--
+exec >/var/tmp/1
+O=v1.6.0.1-266-gaf9552f
+echo O=$(git describe master)
+git shortlog --no-merges $O..master ^maint
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 841bead9db..a1e9100f9e 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -71,7 +71,7 @@ run git diff --check on your changes before you commit.
(1a) Try to be nice to older C compilers
-We try to support wide range of C compilers to compile
+We try to support a wide range of C compilers to compile
git with. That means that you should not use C99 initializers, even
if a lot of compilers grok it.
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 87b028fbc1..5dda70de96 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -581,6 +581,10 @@ diff.autorefreshindex::
affects only 'git-diff' Porcelain, and not lower level
'diff' commands, such as 'git-diff-files'.
+diff.suppress-blank-empty::
+ A boolean to inhibit the standard behavior of printing a space
+ before each empty output line. Defaults to false.
+
diff.external::
If this config variable is set, diff generation is not
performed using the internal diff machinery, but using the
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 746646bb3d..6e268326da 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -106,9 +106,9 @@ endif::git-format-patch[]
--exit-code.
--full-index::
- Instead of the first handful characters, show full
- object name of pre- and post-image blob on the "index"
- line when generating a patch format output.
+ Instead of the first handful of characters, show the full
+ pre- and post-image blob object names on the "index"
+ line when generating patch format output.
--binary::
In addition to --full-index, output "binary diff" that
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 5aa69c0e12..be54a0299f 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -8,7 +8,7 @@ git-checkout - Checkout a branch or paths to the working tree
SYNOPSIS
--------
[verse]
-'git checkout' [-q] [-f] [[--track | --no-track] -b <new_branch> [-l]] [-m] [<branch>]
+'git checkout' [-q] [-f] [--track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>]
'git checkout' [<tree-ish>] [--] <paths>...
DESCRIPTION
@@ -21,6 +21,10 @@ specified, <new_branch>. Using -b will cause <new_branch> to
be created; in this case you can use the --track or --no-track
options, which will be passed to `git branch`.
+As a convenience, --track will default to create a branch whose
+name is constructed from the specified branch name by stripping
+the first namespace level.
+
When <paths> are given, this command does *not* switch
branches. It updates the named paths in the working tree from
the index file (i.e. it runs `git checkout-index -f -u`), or
@@ -59,6 +63,17 @@ OPTIONS
'git-checkout' and 'git-branch' to always behave as if '--no-track' were
given. Set it to `always` if you want this behavior when the
start-point is either a local or remote branch.
++
+If no '-b' option was given, the name of the new branch will be
+derived from the remote branch, by attempting to guess the name
+of the branch on remote system. If "remotes/" or "refs/remotes/"
+are prefixed, it is stripped away, and then the part up to the
+next slash (which would be the nickname of the remote) is removed.
+This would tell us to use "hack" as the local branch when branching
+off of "origin/hack" (or "remotes/origin/hack", or even
+"refs/remotes/origin/hack"). If the given name has no slash, or the above
+guessing results in an empty name, the guessing is aborted. You can
+exlicitly give a name with '-b' in such a case.
--no-track::
Ignore the branch.autosetupmerge configuration variable.
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 0e25bb8627..eb05b0f49b 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -75,8 +75,10 @@ OPTIONS
read the message from the standard input.
--author=<author>::
- Override the author name used in the commit. Use
- `A U Thor <author@example.com>` format.
+ Override the author name used in the commit. You can use the
+ standard `A U Thor <author@example.com>` format. Otherwise,
+ an existing commit that matches the given string and its author
+ name is used.
-m <msg>::
--message=<msg>::
diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt
index 75a8da1ca9..6bc1c21e62 100644
--- a/Documentation/git-count-objects.txt
+++ b/Documentation/git-count-objects.txt
@@ -21,8 +21,9 @@ OPTIONS
--verbose::
In addition to the number of loose objects and disk
space consumed, it reports the number of in-pack
- objects, number of packs, and number of objects that can be
- removed by running `git prune-packed`.
+ objects, number of packs, disk space consumed by those packs,
+ and number of objects that can be removed by running
+ `git prune-packed`.
Author
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index 4ba4b75c11..b08a08cd95 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -9,8 +9,9 @@ SYNOPSIS
--------
[verse]
'git daemon' [--verbose] [--syslog] [--export-all]
- [--timeout=n] [--init-timeout=n] [--strict-paths]
- [--base-path=path] [--user-path | --user-path=path]
+ [--timeout=n] [--init-timeout=n] [--max-connections=n]
+ [--strict-paths] [--base-path=path] [--base-path-relaxed]
+ [--user-path | --user-path=path]
[--interpolated-path=pathtemplate]
[--reuseaddr] [--detach] [--pid-file=file]
[--enable=service] [--disable=service]
@@ -99,6 +100,10 @@ OPTIONS
it takes for the server to process the sub-request and time spent
waiting for next client's request.
+--max-connections::
+ Maximum number of concurrent clients, defaults to 32. Set it to
+ zero for no limit.
+
--syslog::
Log to syslog instead of stderr. Note that this option does not imply
--verbose, thus by default only error conditions will be logged.
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 1fdf20dcc9..5d48664e62 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -49,13 +49,22 @@ include::diff-options.txt[]
--stdin::
When '--stdin' is specified, the command does not take
<tree-ish> arguments from the command line. Instead, it
- reads either one <commit> or a list of <commit>
- separated with a single space from its standard input.
+ reads lines containing either two <tree>, one <commit>, or a
+ list of <commit> from its standard input. (Use a single space
+ as separator.)
+
-When a single commit is given on one line of such input, it compares
-the commit with its parents. The following flags further affects its
-behavior. The remaining commits, when given, are used as if they are
+When two trees are given, it compares the first tree with the second.
+When a single commit is given, it compares the commit with its
+parents. The remaining commits, when given, are used as if they are
parents of the first commit.
++
+When comparing two trees, the ID of both trees (separated by a space
+and terminated by a newline) is printed before the difference. When
+comparing commits, the ID of the first (or only) commit, followed by a
+newline, is printed.
++
+The following flags further affects the behavior when comparing
+commits (but not trees).
-m::
By default, 'git-diff-tree --stdin' does not show
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index ac928e198e..0af40cfb85 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -8,7 +8,9 @@ git-hash-object - Compute object ID and optionally creates a blob from a file
SYNOPSIS
--------
-'git hash-object' [-t <type>] [-w] [--stdin | --stdin-paths] [--] <file>...
+[verse]
+'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin] [--] <file>...
+'git hash-object' [-t <type>] [-w] --stdin-paths < <list-of-paths>
DESCRIPTION
-----------
@@ -35,6 +37,22 @@ OPTIONS
--stdin-paths::
Read file names from stdin instead of from the command-line.
+--path::
+ Hash object as it were located at the given path. The location of
+ file does not directly influence on the hash value, but path is
+ used to determine what git filters should be applied to the object
+ before it can be placed to the object database, and, as result of
+ applying filters, the actual blob put into the object database may
+ differ from the given file. This option is mainly useful for hashing
+ temporary files located outside of the working directory or files
+ read from stdin.
+
+--no-filters::
+ Hash the contents as is, ignoring any input filter that would
+ have been chosen by the attributes mechanism, including crlf
+ conversion. If the file is read from standard input then this
+ is always implied, unless the --path option is given.
+
Author
------
Written by Junio C Hamano <gitster@pobox.com>
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index f414583fc4..d9b9c34b3a 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -112,7 +112,9 @@ For example, this configuration:
will try to use konqueror first. But this may fail (for example if
DISPLAY is not set) and in that case emacs' woman mode will be tried.
-If everything fails the 'man' program will be tried anyway.
+If everything fails, or if no viewer is configured, the viewer specified
+in the GIT_MAN_VIEWER environment variable will be tried. If that
+fails too, the 'man' program will be tried anyway.
man.<tool>.path
~~~~~~~~~~~~~~~
diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index b3d8da33ee..bd49a0aee8 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -3,7 +3,7 @@ git-imap-send(1)
NAME
----
-git-imap-send - Dump a mailbox from stdin into an imap folder
+git-imap-send - Send a collection of patches from stdin to an IMAP folder
SYNOPSIS
@@ -13,9 +13,9 @@ SYNOPSIS
DESCRIPTION
-----------
-This command uploads a mailbox generated with git-format-patch
-into an imap drafts folder. This allows patches to be sent as
-other email is sent with mail clients that cannot read mailbox
+This command uploads a mailbox generated with 'git-format-patch'
+into an IMAP drafts folder. This allows patches to be sent as
+other email is when using mail clients that cannot read mailbox
files directly.
Typical usage is something like:
@@ -26,21 +26,75 @@ git format-patch --signoff --stdout --attach origin | git imap-send
CONFIGURATION
-------------
-'git-imap-send' requires the following values in the repository
-configuration file (shown with examples):
+To use the tool, imap.folder and either imap.tunnel or imap.host must be set
+to appropriate values.
+
+Variables
+~~~~~~~~~
+
+imap.folder::
+ The folder to drop the mails into, which is typically the Drafts
+ folder. For example: "INBOX.Drafts", "INBOX/Drafts" or
+ "[Gmail]/Drafts". Required to use imap-send.
+
+imap.tunnel::
+ Command used to setup a tunnel to the IMAP server through which
+ commands will be piped instead of using a direct network connection
+ to the server. Required when imap.host is not set to use imap-send.
+
+imap.host::
+ A URL identifying the server. Use a `imap://` prefix for non-secure
+ connections and a `imaps://` prefix for secure connections.
+ Ignored when imap.tunnel is set, but required to use imap-send
+ otherwise.
+
+imap.user::
+ The username to use when logging in to the server.
+
+imap.password::
+ The password to use when logging in to the server.
+
+imap.port::
+ An integer port number to connect to on the server.
+ Defaults to 143 for imap:// hosts and 993 for imaps:// hosts.
+ Ignored when imap.tunnel is set.
+
+imap.sslverify::
+ A boolean to enable/disable verification of the server certificate
+ used by the SSL/TLS connection. Default is `true`. Ignored when
+ imap.tunnel is set.
+
+Examples
+~~~~~~~~
+
+Using tunnel mode:
..........................
[imap]
- Folder = "INBOX.Drafts"
+ folder = "INBOX.Drafts"
+ tunnel = "ssh -q -C user@example.com /usr/bin/imapd ./Maildir 2> /dev/null"
+..........................
+Using direct mode:
+
+.........................
[imap]
- Tunnel = "ssh -q user@server.com /usr/bin/imapd ./Maildir 2> /dev/null"
+ folder = "INBOX.Drafts"
+ host = imap://imap.example.com
+ user = bob
+ pass = p4ssw0rd
+..........................
+
+Using direct mode with SSL:
+.........................
[imap]
- Host = imap.server.com
- User = bob
- Pass = pwd
- Port = 143
+ folder = "INBOX.Drafts"
+ host = imaps://imap.example.com
+ user = bob
+ pass = p4ssw0rd
+ port = 123
+ sslverify = false
..........................
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index 1a7ecbf8f3..2f0c5259e0 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -8,26 +8,81 @@ git-merge-base - Find as good common ancestors as possible for a merge
SYNOPSIS
--------
-'git merge-base' [--all] <commit> <commit>
+'git merge-base' [--all] <commit> <commit>...
DESCRIPTION
-----------
-'git-merge-base' finds as good a common ancestor as possible between
-the two commits. That is, given two commits A and B, `git merge-base A
-B` will output a commit which is reachable from both A and B through
-the parent relationship.
+'git-merge-base' finds best common ancestor(s) between two commits to use
+in a three-way merge. One common ancestor is 'better' than another common
+ancestor if the latter is an ancestor of the former. A common ancestor
+that does not have any better common ancestor than it is a 'best common
+ancestor', i.e. a 'merge base'. Note that there can be more than one
+merge bases between two commits.
-Given a selection of equally good common ancestors it should not be
-relied on to decide in any particular way.
-
-The 'git-merge-base' algorithm is still in flux - use the source...
+Among the two commits to compute their merge bases, one is specified by
+the first commit argument on the command line; the other commit is a
+(possibly hypothetical) commit that is a merge across all the remaining
+commits on the command line. As the most common special case, giving only
+two commits from the command line means computing the merge base between
+the given two commits.
OPTIONS
-------
--all::
- Output all common ancestors for the two commits instead of
- just one.
+ Output all merge bases for the commits, instead of just one.
+
+DISCUSSION
+----------
+
+Given two commits 'A' and 'B', `git merge-base A B` will output a commit
+which is reachable from both 'A' and 'B' through the parent relationship.
+
+For example, with this topology:
+
+ o---o---o---B
+ /
+ ---o---1---o---o---o---A
+
+the merge base between 'A' and 'B' is '1'.
+
+Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the
+merge base between 'A' and an hypothetical commit 'M', which is a merge
+between 'B' and 'C'. For example, with this topology:
+
+ o---o---o---o---C
+ /
+ / o---o---o---B
+ / /
+ ---2---1---o---o---o---A
+
+the result of `git merge-base A B C` is '1'. This is because the
+equivalent topology with a merge commit 'M' between 'B' and 'C' is:
+
+
+ o---o---o---o---o
+ / \
+ / o---o---o---o---M
+ / /
+ ---2---1---o---o---o---A
+
+and the result of `git merge-base A M` is '1'. Commit '2' is also a
+common ancestor between 'A' and 'M', but '1' is a better common ancestor,
+because '2' is an ancestor of '1'. Hence, '2' is not a merge base.
+
+When the history involves criss-cross merges, there can be more than one
+'best' common ancestors between two commits. For example, with this
+topology:
+
+ ---1---o---A
+ \ /
+ X
+ / \
+ ---2---o---o---B
+
+both '1' and '2' are merge-base of A and B. Neither one is better than
+the other (both are 'best' merge base). When `--all` option is not given,
+it is unspecified which best one is output.
Author
------
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 17a15acb07..685e1fed58 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -126,13 +126,25 @@ After seeing a conflict, you can do two things:
up working tree changes made by 2. and 3.; 'git-reset --hard' can
be used for this.
- * Resolve the conflicts. `git diff` would report only the
- conflicting paths because of the above 2. and 3.
- Edit the working tree files into a desirable shape
- ('git mergetool' can ease this task), 'git-add' or 'git-rm'
- them, to make the index file contain what the merge result
- should be, and run 'git-commit' to commit the result.
+ * Resolve the conflicts. Git will mark the conflicts in
+ the working tree. Edit the files into shape and
+ 'git-add' to the index. 'git-commit' to seal the deal.
+You can work through the conflict with a number of tools:
+
+ * Use a mergetool. 'git mergetool' to launch a graphical
+ mergetool which will work you through the merge.
+
+ * Look at the diffs. 'git diff' will show a three-way diff,
+ highlighting changes from both the HEAD and remote versions.
+
+ * Look at the diffs on their own. 'git log --merge -p <path>'
+ will show diffs first for the HEAD version and then the
+ remote version.
+
+ * Look at the originals. 'git show :1:filename' shows the
+ common ancestor, 'git show :2:filename' shows the HEAD
+ version and 'git show :3:filename' shows the remote version.
SEE ALSO
--------
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index bf33b0cba0..babaa9bc46 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -14,6 +14,8 @@ SYNOPSIS
'git submodule' [--quiet] init [--] [<path>...]
'git submodule' [--quiet] update [--init] [--] [<path>...]
'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
+'git submodule' [--quiet] foreach <command>
+'git submodule' [--quiet] sync [--] [<path>...]
DESCRIPTION
@@ -123,6 +125,30 @@ summary::
in the submodule between the given super project commit and the
index or working tree (switched by --cached) are shown.
+foreach::
+ Evaluates an arbitrary shell command in each checked out submodule.
+ The command has access to the variables $path and $sha1:
+ $path is the name of the submodule directory relative to the
+ superproject, and $sha1 is the commit as recorded in the superproject.
+ Any submodules defined in the superproject but not checked out are
+ ignored by this command. Unless given --quiet, foreach prints the name
+ of each submodule before evaluating the command.
+ A non-zero return from the command in any submodule causes
+ the processing to terminate. This can be overridden by adding '|| :'
+ to the end of the command.
++
+As an example, "git submodule foreach 'echo $path `git rev-parse HEAD`' will
+show the path and currently checked out commit for each submodule.
+
+sync::
+ Synchronizes submodules' remote URL configuration setting
+ to the value specified in .gitmodules. This is useful when
+ submodule URLs change upstream and you need to update your local
+ repositories accordingly.
++
+"git submodule sync" synchronizes all submodules while
+"git submodule sync -- A" synchronizes submodule "A" only.
+
OPTIONS
-------
-q::
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 53da9b4f6b..2ae771f2fb 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -311,10 +311,16 @@ patterns are available:
- `bibtex` suitable for files with BibTeX coded references.
+- `html` suitable for HTML/XHTML documents.
+
- `java` suitable for source code in the Java language.
- `pascal` suitable for source code in the Pascal/Delphi language.
+- `php` suitable for source code in the PHP language.
+
+- `python` suitable for source code in the Python language.
+
- `ruby` suitable for source code in the Ruby language.
- `tex` suitable for source code for LaTeX documents.
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 735cf07b20..0ce916a188 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -409,6 +409,48 @@ Note that without '\--full-history', this still simplifies merges: if
one of the parents is TREESAME, we follow only that one, so the other
sides of the merge are never walked.
+Finally, there is a fourth simplification mode available:
+
+--simplify-merges::
+
+ First, build a history graph in the same way that
+ '\--full-history' with parent rewriting does (see above).
++
+Then simplify each commit `C` to its replacement `C'` in the final
+history according to the following rules:
++
+--
+* Set `C'` to `C`.
++
+* Replace each parent `P` of `C'` with its simplification `P'`. In
+ the process, drop parents that are ancestors of other parents, and
+ remove duplicates.
++
+* If after this parent rewriting, `C'` is a root or merge commit (has
+ zero or >1 parents), a boundary commit, or !TREESAME, it remains.
+ Otherwise, it is replaced with its only parent.
+--
++
+The effect of this is best shown by way of comparing to
+'\--full-history' with parent rewriting. The example turns into:
++
+-----------------------------------------------------------------------
+ .-A---M---N---O
+ / / /
+ I B D
+ \ / /
+ `---------'
+-----------------------------------------------------------------------
++
+Note the major differences in `N` and `P` over '\--full-history':
++
+--
+* `N`'s parent list had `I` removed, because it is an ancestor of the
+ other parent `M`. Still, `N` remained because it is !TREESAME.
++
+* `P`'s parent list similarly had `I` removed. `P` was then
+ removed completely, because it had one parent and is TREESAME.
+--
ifdef::git-rev-list[]
Bisection Helpers