9 files changed, 94 insertions, 41 deletions

diff --git a/Documentation/RelNotes-1.6.0.txt b/Documentation/RelNotes-1.6.0.txt
index 5292bd730c..03e3a59ff5 100644
--- a/Documentation/RelNotes-1.6.0.txt
+++ b/Documentation/RelNotes-1.6.0.txt
@@ -7,20 +7,16 @@ User visible changes
 [[Note that none of these are not merged to 'master' as of this writing
 but they will be before 1.6.0 happens]]
 
-With default Makefile settings, most of the programs are now installed
-outside your $PATH, except for "git", "gitk", "git-gui" and some server
-side programs that needs to be accessible when connecting over ssh.
-
-When talking to remote repository over ssh, necessary server side programs
-are now invoked with "git $program" notation, not with "git-$program"
-notation.  This should work with both servers running older git where you
-had all of these programs installed on $PATH, or newer git where you have
-only "git" on $PATH.  However, if the remote side is running a custom
-software that restricts programs you can run over ssh, it might cause
-problems.  Use --upload-pack="git-upload-pack" (when using ls-remote,
-fetch and pull on the client side), --receive-pack="git-receive-pack"
-(when using push on the client side), or --exec="git-upload-archive" (when
-using git-archive) as appropriate when talking to such a remote.
+With the default Makefile settings, most of the programs are now
+installed outside your $PATH, except for "git", "gitk", "git-gui" and
+some server side programs that need to be accessible for technical
+reasons.  Invoking a git subcommand as "git-xyzzy" from the command
+line has been deprecated since early 2006 (and officially announced in
+1.5.4 release notes); use of them from your scripts after adding
+output from "git --exec-path" to the $PATH is still supported in this
+release, but users are again strongly encouraged to adjust their
+scripts to use "git xyzzy" form, as we will stop installing
+"git-xyzzy" hardlinks for built-in commands in later releases.
 
 Source changes needed for porting to MinGW environment are now all in the
 main git.git codebase.
@@ -31,6 +27,9 @@ Updates since v1.5.6
 
 (subsystems)
 
+* git-p4 in contrib learned "allowSubmit" configuration to control on
+  which branch to allow "submit" subcommand.
+
 (portability)
 
 * Sample hook scripts shipped in templates/ are now suffixed with
@@ -47,7 +46,13 @@ Updates since v1.5.6
 
 * Updated howto/update-hook-example
 
-(performance, robustness etc.)
+* Got rid of usage of "git-foo" from the tutorial.
+
+* Disambiguating "--" between revs and paths is finally documented.
+
+(performance, robustness, sanity etc.)
+
+* even more documentation pages are now accessible via "man" and "git help".
 
 * reduced excessive inlining to shrink size of the "git" binary.
 
@@ -67,6 +72,9 @@ Updates since v1.5.6
   objects created will be fsync'ed (this is only useful on filesystems
   that does not order data writes properly).
 
+* "git commit-tree" plumbing can make Octopus with more than 16 parents.
+  "git commit" has been capable of this for quite some time.
+
 (usability, bells and whistles)
 
 * git-archive can be told to omit certain paths from its output using
@@ -100,6 +108,6 @@ this release, unless otherwise noted.
 
 ---
 exec >/var/tmp/1
-O=v1.5.6.1-77-gf9a08f6
+O=v1.5.6.1-104-ga08b868
 echo O=$(git describe refs/heads/master)
 git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 10c1a151a4..40d43b78ee 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -8,6 +8,7 @@
 # the command.
 
 [attributes]
+asterisk=*
 plus=+
 caret=^
 startsb=[
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 90c8a45a2f..561ff645f9 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -945,9 +945,17 @@ pack.indexVersion::
 	legacy pack index used by Git versions prior to 1.5.2, and 2 for
 	the new pack index with capabilities for packs larger than 4 GB
 	as well as proper protection against the repacking of corrupted
-	packs.  Version 2 is selected and this config option ignored
-	whenever the corresponding pack is larger than 2 GB.  Otherwise
-	the default is 1.
+	packs.  Version 2 is the default.  Note that version 2 is enforced
+	and this config option ignored whenever the corresponding pack is
+	larger than 2 GB.
++
+If you have an old git that does not understand the version 2 `{asterisk}.idx` file,
+cloning or fetching over a non native protocol (e.g. "http" and "rsync")
+that will copy both `{asterisk}.pack` file and corresponding `{asterisk}.idx` file from the
+other side may give you a repository that cannot be accessed with your
+older version of git. If the `{asterisk}.pack` file is smaller than 2 GB, however,
+you can use linkgit:git-index-pack[1] on the *.pack file to regenerate
+the `{asterisk}.idx` file.
 
 pack.packSizeLimit::
 	The default maximum size of a pack.  This setting only affects
@@ -1004,12 +1012,12 @@ remotes.<group>::
 	<group>".  See linkgit:git-remote[1].
 
 repack.usedeltabaseoffset::
-	Allow linkgit:git-repack[1] to create packs that uses
-	delta-base offset.  Defaults to false.
-
-show.difftree::
-	The default linkgit:git-diff-tree[1] arguments to be used
-	for linkgit:git-show[1].
+	By default, linkgit:git-repack[1] creates packs that use
+	delta-base offset. If you need to share your repository with
+	git older than version 1.4.4, either directly or via a dumb
+	protocol such as http, then you need to set this option to
+	"false" and repack. Access from old git versions over the
+	native protocol are unaffected by this option.
 
 showbranch.default::
 	The default set of branches for linkgit:git-show-branch[1].
@@ -1075,10 +1083,6 @@ user.signingkey::
 	unchanged to gpg's --local-user parameter, so you may specify a key
 	using any method that gpg supports.
 
-whatchanged.difftree::
-	The default linkgit:git-diff-tree[1] arguments to be used
-	for linkgit:git-whatchanged[1].
-
 imap::
 	The configuration variables in the 'imap' section are described
 	in linkgit:git-imap-send[1].
diff --git a/Documentation/git-parse-remote.txt b/Documentation/git-parse-remote.txt
index 951dbd6c83..421312eca9 100644
--- a/Documentation/git-parse-remote.txt
+++ b/Documentation/git-parse-remote.txt
@@ -8,7 +8,7 @@ git-parse-remote - Routines to help parsing remote repository access parameters
 
 SYNOPSIS
 --------
-'. git-parse-remote'
+'. "$(git --exec-path)/git-parse-remote"'
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 9e273bc5a6..59e95adf42 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -184,7 +184,10 @@ blobs contained in a commit.
   second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
   of the ref at a prior point in time.  This suffix may only be
   used immediately following a ref name and the ref must have an
-  existing log ($GIT_DIR/logs/<ref>).
+  existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state
+  of your *local* ref at a given time; e.g., what was in your local
+  `master` branch last week. If you want to look at commits made during
+  certain times, see `--since` and `--until`.
 
 * A ref followed by the suffix '@' with an ordinal specification
   enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 251d661afd..dc7eb7bd4e 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -133,10 +133,13 @@ or on the command line. If a username has been specified (with
 specified (with --smtp-pass or a configuration variable), then the
 user is prompted for a password while the input is masked for privacy.
 
+--smtp-encryption::
+	Specify the encryption to use, either 'ssl' or 'tls'.  Any other
+	value reverts to plain SMTP.  Default is the value of
+	'sendemail.smtpencryption'.
+
 --smtp-ssl::
-	If set, connects to the SMTP server using SSL.
-	Default is the value of the 'sendemail.smtpssl' configuration value;
-	if that is unspecified, does not use SSL.
+	Legacy alias for '--smtp-encryption=ssl'.
 
 --subject::
 	Specify the initial subject of the email thread.
@@ -229,8 +232,13 @@ sendemail.smtpuser::
 sendemail.smtppass::
 	Default SMTP-AUTH password.
 
+sendemail.smtpencryption::
+	Default encryption method.  Use 'ssl' for SSL (and specify an
+	appropriate port), or 'tls' for TLS.  Takes precedence over
+	'smtpssl' if both are specified.
+
 sendemail.smtpssl::
-	Boolean value specifying the default to the '--smtp-ssl' parameter.
+	Legacy boolean that sets 'smtpencryption=ssl' if enabled.
 
 Author
 ------
diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt
index c543170342..6731f9ac4c 100644
--- a/Documentation/git-sh-setup.txt
+++ b/Documentation/git-sh-setup.txt
@@ -7,7 +7,7 @@ git-sh-setup - Common git shell script setup code
 
 SYNOPSIS
 --------
-'git-sh-setup'
+'. "$(git --exec-path)/git-sh-setup"'
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 97bed54fbd..c350ad0f83 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -513,7 +513,7 @@ have each person clone that repository with 'git clone':
 	cd project
 	git-init
 	git remote add origin server:/pub/project
-	git config --add remote.origin.fetch=+refs/remotes/*:refs/remotes/*
+	git config --add remote.origin.fetch '+refs/remotes/*:refs/remotes/*'
 	git fetch
 # Initialize git-svn locally (be sure to use the same URL and -T/-b/-t options as were used on server)
 	git-svn init http://svn.foo.org/project
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 8fb5d889e5..2316049865 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -13,8 +13,37 @@ gitcli
 DESCRIPTION
 -----------
 
-This manual describes best practice in how to use git CLI.  Here are
-the rules that you should follow when you are scripting git:
+This manual describes the convention used throughout git CLI.
+
+Many commands take revisions (most often "commits", but sometimes
+"tree-ish", depending on the context and command) and paths as their
+arguments.  Here are the rules:
+
+ * Revisions come first and then paths.
+   E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`,
+   `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86`
+   are paths.
+
+ * When an argument can be misunderstood as either a revision or a path,
+   they can be disambiguated by placing `\--` between them.
+   E.g. `git diff \-- HEAD` is, "I have a file called HEAD in my work
+   tree.  Please show changes between the version I staged in the index
+   and what I have in the work tree for that file". not "show difference
+   between the HEAD commit and the work tree as a whole".  You can say
+   `git diff HEAD \--` to ask for the latter.
+
+ * Without disambiguating `\--`, git makes a reasonable guess, but errors
+   out and asking you to disambiguate when ambiguous.  E.g. if you have a
+   file called HEAD in your work tree, `git diff HEAD` is ambiguous, and
+   you have to say either `git diff HEAD \--` or `git diff \-- HEAD` to
+   disambiguate.
+
+When writing a script that is expected to handle random user-input, it is
+a good practice to make it explicit which arguments are which by placing
+disambiguating `\--` at appropriate places.
+
+Here are the rules regarding the "flags" that you should follow when you are
+scripting git:
 
  * it's preferred to use the non dashed form of git commands, which means that
    you should prefer `"git foo"` to `"git-foo"`.
@@ -34,8 +63,8 @@ the rules that you should follow when you are scripting git:
    if you happen to have a file called `HEAD` in the work tree.
 
 
-ENHANCED CLI
-------------
+ENHANCED OPTION PARSER
+----------------------
 From the git 1.5.4 series and further, many git commands (not all of them at the
 time of the writing though) come with an enhanced option parser.