summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/Makefile44
-rw-r--r--Documentation/RelNotes/1.8.3.2.txt59
-rw-r--r--Documentation/RelNotes/1.8.4.txt73
-rw-r--r--Documentation/config.txt14
-rw-r--r--Documentation/git-config.txt9
-rw-r--r--Documentation/git-diff.txt14
-rw-r--r--Documentation/git-log.txt4
-rw-r--r--Documentation/git-merge.txt4
-rw-r--r--Documentation/git-name-rev.txt3
-rw-r--r--Documentation/git-push.txt9
-rw-r--r--Documentation/git-rev-parse.txt16
-rw-r--r--Documentation/git-stash.txt13
-rw-r--r--Documentation/git-web--browse.txt1
-rw-r--r--Documentation/git.txt16
-rw-r--r--Documentation/rev-list-options.txt42
-rw-r--r--Documentation/technical/api-builtin.txt2
-rw-r--r--Documentation/technical/api-parse-options.txt12
-rw-r--r--Documentation/user-manual.txt19
18 files changed, 277 insertions, 77 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 62dbd9ac7c..0cfdc36b44 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -31,11 +31,11 @@ MAN7_TXT += gittutorial.txt
MAN7_TXT += gitworkflows.txt
MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
-MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
-MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
+MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
+MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
OBSOLETE_HTML = git-remote-helpers.html
-DOC_HTML=$(MAN_HTML) $(OBSOLETE_HTML)
+DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
ARTICLES = howto-index
ARTICLES += everyday
@@ -74,35 +74,35 @@ SP_ARTICLES += technical/api-index
DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
-DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT))
-DOC_MAN5=$(patsubst %.txt,%.5,$(MAN5_TXT))
-DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT))
-
-prefix?=$(HOME)
-bindir?=$(prefix)/bin
-htmldir?=$(prefix)/share/doc/git-doc
-pdfdir?=$(prefix)/share/doc/git-doc
-mandir?=$(prefix)/share/man
-man1dir=$(mandir)/man1
-man5dir=$(mandir)/man5
-man7dir=$(mandir)/man7
-# DESTDIR=
+DOC_MAN1 = $(patsubst %.txt,%.1,$(MAN1_TXT))
+DOC_MAN5 = $(patsubst %.txt,%.5,$(MAN5_TXT))
+DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT))
+
+prefix ?= $(HOME)
+bindir ?= $(prefix)/bin
+htmldir ?= $(prefix)/share/doc/git-doc
+infodir ?= $(prefix)/share/info
+pdfdir ?= $(prefix)/share/doc/git-doc
+mandir ?= $(prefix)/share/man
+man1dir = $(mandir)/man1
+man5dir = $(mandir)/man5
+man7dir = $(mandir)/man7
+# DESTDIR =
ASCIIDOC = asciidoc
ASCIIDOC_EXTRA =
MANPAGE_XSL = manpage-normal.xsl
XMLTO = xmlto
XMLTO_EXTRA =
-INSTALL?=install
+INSTALL ?= install
RM ?= rm -f
MAN_REPO = ../../git-manpages
HTML_REPO = ../../git-htmldocs
-infodir?=$(prefix)/share/info
-MAKEINFO=makeinfo
-INSTALL_INFO=install-info
-DOCBOOK2X_TEXI=docbook2x-texi
-DBLATEX=dblatex
+MAKEINFO = makeinfo
+INSTALL_INFO = install-info
+DOCBOOK2X_TEXI = docbook2x-texi
+DBLATEX = dblatex
ifndef PERL_PATH
PERL_PATH = /usr/bin/perl
endif
diff --git a/Documentation/RelNotes/1.8.3.2.txt b/Documentation/RelNotes/1.8.3.2.txt
new file mode 100644
index 0000000000..26ae142c3d
--- /dev/null
+++ b/Documentation/RelNotes/1.8.3.2.txt
@@ -0,0 +1,59 @@
+Git v1.8.3.2 Release Notes
+==========================
+
+Fixes since v1.8.3.1
+--------------------
+
+ * Cloning with "git clone --depth N" while fetch.fsckobjects (or
+ transfer.fsckobjects) is set to true did not tell the cut-off
+ points of the shallow history to the process that validates the
+ objects and the history received, causing the validation to fail.
+
+ * "git checkout foo" DWIMs the intended "upstream" and turns it into
+ "git checkout -t -b foo remotes/origin/foo". This codepath has been
+ updated to correctly take existing remote definitions into account.
+
+ * "git fetch" into a shallow repository from a repository that does
+ not know about the shallow boundary commits (e.g. a different fork
+ from the repository the current shallow repository was cloned from)
+ did not work correctly.
+
+ * "git subtree" (in contrib/) had one codepath with loose error
+ checks to lose data at the remote side.
+
+ * "git log --ancestry-path A...B" did not work as expected, as it did
+ not pay attention to the fact that the merge base between A and B
+ was the bottom of the range being specified.
+
+ * "git diff -c -p" was not showing a deleted line from a hunk when
+ another hunk immediately begins where the earlier one ends.
+
+ * "git merge @{-1}~22" was rewritten to "git merge frotz@{1}~22"
+ incorrectly when your previous branch was "frotz" (it should be
+ rewritten to "git merge frotz~22" instead).
+
+ * "git commit --allow-empty-message -m ''" should not start an
+ editor.
+
+ * "git push --[no-]verify" was not documented.
+
+ * An entry for "file://" scheme in the enumeration of URL types Git
+ can take in the HTML documentation was made into a clickable link
+ by mistake.
+
+ * zsh prompt script that borrowed from bash prompt script did not
+ work due to slight differences in array variable notation between
+ these two shells.
+
+ * The bash prompt code (in contrib/) displayed the name of the branch
+ being rebased when "rebase -i/-m/-p" modes are in use, but not the
+ plain vanilla "rebase".
+
+ * "git push $there HEAD:branch" did not resolve HEAD early enough, so
+ it was easy to flip it around while push is still going on and push
+ out a branch that the user did not originally intended when the
+ command was started.
+
+ * "difftool --dir-diff" did not copy back changes made by the
+ end-user in the diff tool backend to the working tree in some
+ cases.
diff --git a/Documentation/RelNotes/1.8.4.txt b/Documentation/RelNotes/1.8.4.txt
index b974d492dc..1854d1723d 100644
--- a/Documentation/RelNotes/1.8.4.txt
+++ b/Documentation/RelNotes/1.8.4.txt
@@ -4,7 +4,12 @@ Git v1.8.4 Release Notes
Updates since v1.8.3
--------------------
-Foreign interfaces and ports.
+Foreign interfaces, subsystems and ports.
+
+ * Git-gui has been updated to its 0.18.0 version.
+
+ * MediaWiki remote helper (in contrib/) has been updated to use the
+ credential helper interface from Git.pm.
* Update build for Cygwin 1.[57]. Torsten Bögershausen reports that
this is fine with Cygwin 1.7 ($gmane/225824) so let's try moving it
@@ -30,6 +35,23 @@ Foreign interfaces and ports.
UI, Workflows & Features
+ * "git rm" gives a single message followed by list of paths to report
+ multiple paths that cannot be removed.
+
+ * "git rebase" can be told with ":/look for this string" syntax commits
+ to replay the changes onto and where the work to be replayed begins.
+
+ * Many tutorials teach users to set "color.ui" to "auto" as the first
+ thing after you set "user.name/email" to introduce yourselves to
+ Git. Now the variable defaults to "auto".
+
+ * On Cygwin, "cygstart" is now recognised as a possible way to start
+ a web browser (used in "help -w" and "instaweb" among others).
+
+### * "git status" learned status.branch and status.short configuration
+### variables to use --branch and --short options by default (override
+### with --no-branch and --no-short options from the command line).
+
* "git cmd <name>", when <name> happens to be a 40-hex string,
directly uses the 40-hex string as an object name, even if a ref
"refs/<some hierarchy>/<name>" exists. This disambiguation order
@@ -39,7 +61,8 @@ UI, Workflows & Features
* "git rebase" learned "--[no-]autostash" option to save local
changes instead of refusing to run (to which people's normal
- response was to stash them and re-run).
+ response was to stash them and re-run). This introduced a corner
+ case breakage to "git am --abort" but it has been fixed.
* Instead of typing four capital letters "HEAD", you can say "@" now,
e.g. "git log @".
@@ -85,6 +108,18 @@ UI, Workflows & Features
Performance, Internal Implementation, etc.
+ * Uses of the platform fnmatch(3) function (many places in the code,
+ matching pathspec, .gitignore and .gitattributes to name a few)
+ have been replaced with wildmatch, allowing "foo/**/bar" that would
+ match foo/bar, foo/a/bar, foo/a/b/bar, etc.
+
+ * Memory ownership and lifetime rules for what for-each-ref feeds to
+ its callbacks have been clarified (in short, "you do not own it, so
+ make a copy if you want to keep it").
+
+ * The revision traversal logic to improve culling of irrelevant
+ parents while traversing a mergy history has been updated.
+
* Some leaks in unpack-trees (used in merge, cherry-pick and other
codepaths) have been plugged.
@@ -122,6 +157,40 @@ Unless otherwise noted, all the fixes since v1.8.3 in the maintenance
track are contained in this release (see release notes to them for
details).
+ * "git apply" parsed patches that add new files, generated by
+ programs other than Git, incorrectly. This is an old breakage in
+ v1.7.11 and will need to be merged down to the maintanance tracks.
+ (merge 212eb96 tr/maint-apply-non-git-patch-parsefix later to maint).
+
+ * Older cURL wanted piece of memory we call it with to be stable, but
+ we updated the auth material after handing it to a call.
+ (merge a94cf2c bc/http-keep-memory-given-to-curl later to maint).
+
+ * "git pull" into nothing trashed "local changes" that were in the
+ index, and this avoids it.
+ (merge b4dc085 jk/pull-into-dirty-unborn later to maint).
+
+ * Many "git submodule" operations do not work on a submodule at a
+ path whose name is not in ASCII.
+ (merge bed9470 fg/submodule-non-ascii-path later to maint).
+
+ * "cherry-pick" had a small leak in an error codepath.
+ (merge 706728a fc/sequencer-plug-leak later to maint).
+
+ * Logic used by git-send-email to suppress cc mishandled names like
+ "A U. Thor" <author@example.xz>, where the human readable part
+ needs to be quoted (the user input may not have the double quotes
+ around the name, and comparison was done between quoted and
+ unquoted strings). It also mishandled names that need RFC2047
+ quoting.
+ (merge 1495266 mt/send-email-cc-match-fix later to maint).
+
+ * Call to discard_cache/discard_index (used when we use different
+ contents of the index in-core, in many operations like commit,
+ apply, and merge) used to leak memory that held the array of index
+ entries, which has been plugged.
+ (merge a0fc4db rs/discard-index-discard-array later to maint).
+
* "gitweb" forgot to clear a global variable $search_regexp upon each
request, mistakenly carrying over the previous search to a new one
when used as a persistent CGI.
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 7fd4035cb5..1153585aa2 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -199,6 +199,9 @@ advice.*::
amWorkDir::
Advice that shows the location of the patch file when
linkgit:git-am[1] fails to apply it.
+ rmHints::
+ In case of failure in the output of linkgit:git-rm[1],
+ show directions on how to proceed from the current state.
--
core.fileMode::
@@ -919,11 +922,12 @@ color.ui::
as `color.diff` and `color.grep` that control the use of color
per command family. Its scope will expand as more commands learn
configuration to set a default for the `--color` option. Set it
- to `always` if you want all output not intended for machine
- consumption to use color, to `true` or `auto` if you want such
- output to use color when written to the terminal, or to `false` or
- `never` if you prefer Git commands not to use color unless enabled
- explicitly with some other configuration or the `--color` option.
+ to `false` or `never` if you prefer Git commands not to use
+ color unless enabled explicitly with some other configuration
+ or the `--color` option. Set it to `always` if you want all
+ output not intended for machine consumption to use color, to
+ `true` or `auto` (this is the default since Git 1.8.4) if you
+ want such output to use color when written to the terminal.
column.ui::
Specify whether supported commands should output in columns.
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index d88a6fcb29..19a7be0856 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -114,6 +114,15 @@ rather than from all available files.
+
See also <<FILES>>.
+--local::
+ For writing options: write to the repository .git/config file.
+ This is the default behavior.
++
+For reading options: read only from the repository .git/config rather than
+from all available files.
++
+See also <<FILES>>.
+
-f config-file::
--file config-file::
Use the given config file instead of the one specified by GIT_CONFIG.
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index a7b46208f6..78d6d50489 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -18,8 +18,8 @@ SYNOPSIS
DESCRIPTION
-----------
Show changes between the working tree and the index or a tree, changes
-between the index and a tree, changes between two trees, or changes
-between two files on disk.
+between the index and a tree, changes between two trees, changes between
+two blob objects, or changes between two files on disk.
'git diff' [--options] [--] [<path>...]::
@@ -56,11 +56,6 @@ directories. This behavior can be forced by --no-index.
This is to view the changes between two arbitrary
<commit>.
-'git diff' [options] <blob> <blob>::
-
- This form is to view the differences between the raw
- contents of two blob objects.
-
'git diff' [--options] <commit>..<commit> [--] [<path>...]::
This is synonymous to the previous form. If <commit> on
@@ -87,6 +82,11 @@ and the range notations ("<commit>..<commit>" and
"<commit>\...<commit>") do not mean a range as defined in the
"SPECIFYING RANGES" section in linkgit:gitrevisions[7].
+'git diff' [options] <blob> <blob>::
+
+ This form is to view the differences between the raw
+ contents of two blob objects.
+
OPTIONS
-------
:git-diff: 1
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 4687fe8192..2ea79ba168 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -128,9 +128,9 @@ Examples
in the "release" branch, along with the list of paths
each commit modifies.
-`git log --follow builtin-rev-list.c`::
+`git log --follow builtin/rev-list.c`::
- Shows the commits that changed builtin-rev-list.c, including
+ Shows the commits that changed builtin/rev-list.c, including
those commits that occurred before the file was given its
present name.
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 67ca99cd92..8c7f2f66d8 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -56,8 +56,8 @@ especially if those changes were further modified after the merge
was started), 'git merge --abort' will in some cases be unable to
reconstruct the original (pre-merge) changes. Therefore:
-*Warning*: Running 'git merge' with uncommitted changes is
-discouraged: while possible, it leaves you in a state that is hard to
+*Warning*: Running 'git merge' with non-trivial uncommitted changes is
+discouraged: while possible, it may leave you in a state that is hard to
back out of in the case of a conflict.
diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt
index ad1d1468c9..6b0f1ba75f 100644
--- a/Documentation/git-name-rev.txt
+++ b/Documentation/git-name-rev.txt
@@ -25,7 +25,8 @@ OPTIONS
Do not use branch names, but only tags to name the commits
--refs=<pattern>::
- Only use refs whose names match a given shell pattern.
+ Only use refs whose names match a given shell pattern. The pattern
+ can be one of branch name, tag name or fully qualified ref name.
--all::
List all commits reachable from all refs
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index df5be268ba..f7dfe48d28 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -136,6 +136,15 @@ already exists on the remote side.
not an ancestor of the local ref used to overwrite it.
This flag disables the check. This can cause the
remote repository to lose commits; use it with care.
+ Note that `--force` applies to all the refs that are pushed,
+ hence using it with `push.default` set to `matching` or with
+ multiple push destinations configured with `remote.*.push`
+ may overwrite refs other than the current branch (including
+ local refs that are strictly behind their remote counterpart).
+ To force a push to only one branch, use a `+` in front of the
+ refspec to push (e.g `git push origin +master` to force a push
+ to the `master` branch). See the `<refspec>...` section above
+ for details.
--repo=<repository>::
This option is only relevant if no <repository> argument is
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 947d62fd25..993903c9f1 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -59,6 +59,22 @@ OPTIONS
If there is no parameter given by the user, use `<arg>`
instead.
+--prefix <arg>::
+ Behave as if 'git rev-parse' was invoked from the `<arg>`
+ subdirectory of the working tree. Any relative filenames are
+ resolved as if they are prefixed by `<arg>` and will be printed
+ in that form.
++
+This can be used to convert arguments to a command run in a subdirectory
+so that they can still be used after moving to the top-level of the
+repository. For example:
++
+----
+prefix=$(git rev-parse --show-prefix)
+cd "$(git rev-parse --show-toplevel)"
+eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")"
+----
+
--verify::
Verify that exactly one parameter is provided, and that it
can be turned into a raw 20-byte SHA-1 that can be used to
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 711ffe17a7..db7e803038 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -13,10 +13,11 @@ SYNOPSIS
'git stash' drop [-q|--quiet] [<stash>]
'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
'git stash' branch <branchname> [<stash>]
-'git stash' [save [--patch] [-k|--[no-]keep-index] [-q|--quiet]
+'git stash' [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]
[-u|--include-untracked] [-a|--all] [<message>]]
'git stash' clear
-'git stash' create
+'git stash' create [<message>]
+'git stash' store [-m|--message <message>] [-q|--quiet] <commit>
DESCRIPTION
-----------
@@ -151,7 +152,15 @@ create::
Create a stash (which is a regular commit object) and return its
object name, without storing it anywhere in the ref namespace.
+ This is intended to be useful for scripts. It is probably not
+ the command you want to use; see "save" above.
+store::
+
+ Store a given stash created via 'git stash create' (which is a
+ dangling merge commit) in the stash ref, updating the stash
+ reflog. This is intended to be useful for scripts. It is
+ probably not the command you want to use; see "save" above.
DISCUSSION
----------
diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt
index ba79cb4f35..5aec4ecffb 100644
--- a/Documentation/git-web--browse.txt
+++ b/Documentation/git-web--browse.txt
@@ -34,6 +34,7 @@ The following browsers (or commands) are currently supported:
* dillo
* open (this is the default under Mac OS X GUI)
* start (this is the default under MinGW)
+* cygstart (this is the default under Cygwin)
Custom commands may also be specified.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 2e23cbb224..b738a40e6b 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -43,9 +43,10 @@ unreleased) version of Git, that is available from 'master'
branch of the `git.git` repository.
Documentation for older releases are available here:
-* link:v1.8.3.1/git.html[documentation for release 1.8.3.1]
+* link:v1.8.3.2/git.html[documentation for release 1.8.3.2]
* release notes for
+ link:RelNotes/1.8.3.2.txt[1.8.3.2],
link:RelNotes/1.8.3.1.txt[1.8.3.1],
link:RelNotes/1.8.3.txt[1.8.3].
@@ -837,6 +838,19 @@ for further details.
as a file path and will try to write the trace messages
into it.
+'GIT_TRACE_PACK_ACCESS'::
+ If this variable is set to a path, a file will be created at
+ the given path logging all accesses to any packs. For each
+ access, the pack file name and an offset in the pack is
+ recorded. This may be helpful for troubleshooting some
+ pack-related performance problems.
+
+'GIT_TRACE_PACKET'::
+ If this variable is set, it shows a trace of all packets
+ coming in or out of a given program. This can help with
+ debugging object negotiation or other protocol issues. Tracing
+ is turned off at a packet starting with "PACK".
+
GIT_LITERAL_PATHSPECS::
Setting this variable to `1` will cause Git to treat all
pathspecs literally, rather than as glob patterns. For example,
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 3bdbf5e856..b462f17f62 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -271,8 +271,8 @@ See also linkgit:git-reflog[1].
--boundary::
- Output uninteresting commits at the boundary, which are usually
- not shown.
+ Output excluded boundary commits. Boundary commits are
+ prefixed with `-`.
--
@@ -342,13 +342,13 @@ In the following, we will always refer to the same example history to
illustrate the differences between simplification settings. We assume
that you are filtering for a file `foo` in this commit graph:
-----------------------------------------------------------------------
- .-A---M---N---O---P
- / / / / /
- I B C D E
- \ / / / /
- `-------------'
+ .-A---M---N---O---P---Q
+ / / / / / /
+ I B C D E Y
+ \ / / / / /
+ `-------------' X
-----------------------------------------------------------------------
-The horizontal line of history A---P is taken to be the first parent of
+The horizontal line of history A---Q is taken to be the first parent of
each merge. The commits are:
* `I` is the initial commit, in which `foo` exists with contents
@@ -367,8 +367,11 @@ each merge. The commits are:
`N` and `D` to "foobarbaz"; i.e., it is not TREESAME to any parent.
* `E` changes `quux` to "xyzzy", and its merge `P` combines the
- strings to "quux xyzzy". Despite appearing interesting, `P` is
- TREESAME to all parents.
+ strings to "quux xyzzy". `P` is TREESAME to `O`, but not to `E`.
+
+* `X` is an indpendent root commit that added a new file `side`, and `Y`
+ modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and
+ `Q` is TREESAME to `P`, but not to `Y`.
'rev-list' walks backwards through history, including or excluding
commits based on whether '\--full-history' and/or parent rewriting
@@ -410,10 +413,10 @@ parent lines.
the example, we get
+
-----------------------------------------------------------------------
- I A B N D O
+ I A B N D O P Q
-----------------------------------------------------------------------
+
-`P` and `M` were excluded because they are TREESAME to a parent. `E`,
+`M` was excluded because it is TREESAME to both parents. `E`,
`C` and `B` were all walked, but only `B` was !TREESAME, so the others
do not appear.
+
@@ -431,7 +434,7 @@ Along each parent, prune away commits that are not included
themselves. This results in
+
-----------------------------------------------------------------------
- .-A---M---N---O---P
+ .-A---M---N---O---P---Q
/ / / / /
I B / D /
\ / / / /
@@ -441,7 +444,7 @@ themselves. This results in
Compare to '\--full-history' without rewriting above. Note that `E`
was pruned away because it is TREESAME, but the parent list of P was
rewritten to contain `E`'s parent `I`. The same happened for `C` and
-`N`. Note also that `P` was included despite being TREESAME.
+`N`, and `X`, `Y` and `Q`.
In addition to the above settings, you can change whether TREESAME
affects inclusion:
@@ -471,8 +474,9 @@ 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.
+ the process, drop parents that are ancestors of other parents or that are
+ root commits TREESAME to an empty tree, and remove duplicates, but take care
+ to never drop all parents that we are TREESAME to.
+
* If after this parent rewriting, `C'` is a root or merge commit (has
zero or >1 parents), a boundary commit, or !TREESAME, it remains.
@@ -490,7 +494,7 @@ The effect of this is best shown by way of comparing to
`---------'
-----------------------------------------------------------------------
+
-Note the major differences in `N` and `P` over '--full-history':
+Note the major differences in `N`, `P` and `Q` over '--full-history':
+
--
* `N`'s parent list had `I` removed, because it is an ancestor of the
@@ -498,6 +502,10 @@ Note the major differences in `N` and `P` over '--full-history':
+
* `P`'s parent list similarly had `I` removed. `P` was then
removed completely, because it had one parent and is TREESAME.
++
+* `Q`'s parent list had `Y` simplified to `X`. `X` was then removed, because it
+ was a TREESAME root. `Q` was then removed completely, because it had one
+ parent and is TREESAME.
--
Finally, there is a fifth simplification mode available:
diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt
index 4a4228b896..f3c1357b7c 100644
--- a/Documentation/technical/api-builtin.txt
+++ b/Documentation/technical/api-builtin.txt
@@ -39,7 +39,7 @@ where options is the bitwise-or of:
on bare repositories.
This only makes sense when `RUN_SETUP` is also set.
-. Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`.
+. Add `builtin/foo.o` to `BUILTIN_OBJS` in `Makefile`.
Additionally, if `foo` is a new command, there are 3 more things to do:
diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index 1317db4d6c..0be2b5159f 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -275,10 +275,10 @@ Examples
--------
See `test-parse-options.c` and
-`builtin-add.c`,
-`builtin-clone.c`,
-`builtin-commit.c`,
-`builtin-fetch.c`,
-`builtin-fsck.c`,
-`builtin-rm.c`
+`builtin/add.c`,
+`builtin/clone.c`,
+`builtin/commit.c`,
+`builtin/fetch.c`,
+`builtin/fsck.c`,
+`builtin/rm.c`
for real-world examples.
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index e831cc2020..644acce079 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -57,10 +57,10 @@ download a copy of an existing repository. If you don't already have a
project in mind, here are some interesting examples:
------------------------------------------------
- # Git itself (approx. 10MB download):
+ # Git itself (approx. 40MB download):
$ git clone git://git.kernel.org/pub/scm/git/git.git
- # the Linux kernel (approx. 150MB download):
-$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
+ # the Linux kernel (approx. 640MB download):
+$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
------------------------------------------------
The initial clone may be time-consuming for a large project, but you
@@ -4256,15 +4256,16 @@ no longer need to call `setup_pager()` directly).
Nowadays, `git log` is a builtin, which means that it is _contained_ in the
command `git`. The source side of a builtin is
-- a function called `cmd_<bla>`, typically defined in `builtin-<bla>.c`,
- and declared in `builtin.h`,
+- a function called `cmd_<bla>`, typically defined in `builtin/<bla.c>`
+ (note that older versions of Git used to have it in `builtin-<bla>.c`
+ instead), and declared in `builtin.h`.
- an entry in the `commands[]` array in `git.c`, and
- an entry in `BUILTIN_OBJECTS` in the `Makefile`.
Sometimes, more than one builtin is contained in one source file. For
-example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin-log.c`,
+example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`,
since they share quite a bit of code. In that case, the commands which are
_not_ named like the `.c` file in which they live have to be listed in
`BUILT_INS` in the `Makefile`.
@@ -4287,10 +4288,10 @@ For the sake of clarity, let's stay with `git cat-file`, because it
- is plumbing, and
- was around even in the initial commit (it literally went only through
- some 20 revisions as `cat-file.c`, was renamed to `builtin-cat-file.c`
+ some 20 revisions as `cat-file.c`, was renamed to `builtin/cat-file.c`
when made a builtin, and then saw less than 10 versions).
-So, look into `builtin-cat-file.c`, search for `cmd_cat_file()` and look what
+So, look into `builtin/cat-file.c`, search for `cmd_cat_file()` and look what
it does.
------------------------------------------------------------------
@@ -4366,7 +4367,7 @@ Another example: Find out what to do in order to make some script a
builtin:
-------------------------------------------------
-$ git log --no-merges --diff-filter=A builtin-*.c
+$ git log --no-merges --diff-filter=A builtin/*.c
-------------------------------------------------
You see, Git is actually the best tool to find out about the source of Git