do not write null sha1s to on-disk index

diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt
index d7f5a51feaeaf1acd804510ddc910f11fcfdbe50..ed827902fc540d098fc548e5bb68ab3ab95ffa25 100644 (file)
--- a/Documentation/git-p4.txt
+++ b/Documentation/git-p4.txt
@@ -230,12 +230,7 @@ git repository:
 
 --use-client-spec::
        Use a client spec to find the list of interesting files in p4.
-       The client spec is discovered using 'p4 client -o' which checks
-       the 'P4CLIENT' environment variable and returns a mapping of
-       depot files to workspace files.  Note that a depot path is
-       still required, but files found in the path that match in
-       the client spec view will be laid out according to the client
-       spec.
+       See the "CLIENT SPEC" section below.
 
 Clone options
 ~~~~~~~~~~~~~
@@ -304,6 +299,31 @@ p4 revision specifier on the end:
 See 'p4 help revisions' for the full syntax of p4 revision specifiers.
 
 
+CLIENT SPEC
+-----------
+The p4 client specification is maintained with the 'p4 client' command
+and contains among other fields, a View that specifies how the depot
+is mapped into the client repository.  The 'clone' and 'sync' commands
+can consult the client spec when given the '--use-client-spec' option or
+when the useClientSpec variable is true.  After 'git p4 clone', the
+useClientSpec variable is automatically set in the repository
+configuration file.  This allows future 'git p4 submit' commands to
+work properly; the submit command looks only at the variable and does
+not have a command-line option.
+
+The full syntax for a p4 view is documented in 'p4 help views'.  Git-p4
+knows only a subset of the view syntax.  It understands multi-line
+mappings, overlays with '+', exclusions with '-' and double-quotes
+around whitespace.  Of the possible wildcards, git-p4 only handles
+'...', and only when it is at the end of the path.  Git-p4 will complain
+if it encounters an unhandled wildcard.
+
+The name of the client can be given to git-p4 in multiple ways.  The
+variable 'git-p4.client' takes precedence if it exists.  Otherwise,
+normal p4 mechanisms of determining the client are used:  environment
+variable P4CLIENT, a file referenced by P4CONFIG, or the local host name.
+
+
 BRANCH DETECTION
 ----------------
 P4 does not have the same concept of a branch as git.  Instead,
@@ -387,9 +407,7 @@ git-p4.host::
 
 git-p4.client::
        Client specified as an option to all p4 commands, with
-       '-c <client>'.  This can also be used as a way to find
-       the client spec for the 'useClientSpec' option.
-       The environment variable 'P4CLIENT' can be used instead.
+       '-c <client>', including the client spec.
 
 Clone and sync variables
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -417,10 +435,10 @@ git config --add git-p4.branchList main:branchB
 -------------
 
 git-p4.useClientSpec::
-       Specify that the p4 client spec to be used to identify p4 depot
-       paths of interest.  This is equivalent to specifying the option
-       '--use-client-spec'.  The variable 'git-p4.client' can be used
-       to specify the name of the client.
+       Specify that the p4 client spec should be used to identify p4
+       depot paths of interest.  This is equivalent to specifying the
+       option '--use-client-spec'.  See the "CLIENT SPEC" section above.
+       This variable is a boolean, not the name of a p4 client.
 
 Submit variables
 ~~~~~~~~~~~~~~~~