archive: improve documentation of --prefix

Document the interaction between --add-file and --prefix by giving an
example.

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: René Scharfe <l.s.r@web.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index bc4e76a7834a59a7ecfd9880d5a51bf794ca1b6c..94519aae231ba4bf8cc44159e60b86cb8a8c7bd4 100644 (file)
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -49,7 +49,9 @@ OPTIONS
        Report progress to stderr.
 
 --prefix=<prefix>/::
        Report progress to stderr.
 
 --prefix=<prefix>/::

-       Prepend <prefix>/ to each filename in the archive.
+       Prepend <prefix>/ to paths in the archive.  Can be repeated; its
+       rightmost value is used for all tracked files.  See below which
+       value gets used by `--add-file`.

 
 -o <file>::
 --output=<file>::
 
 -o <file>::
 --output=<file>::


@@ -57,9 +59,9 @@ OPTIONS
 
 --add-file=<file>::
        Add a non-tracked file to the archive.  Can be repeated to add
 
 --add-file=<file>::
        Add a non-tracked file to the archive.  Can be repeated to add

-       multiple files.  The path of the file in the archive is built
-       by concatenating the value for `--prefix` (if any) and the
-       basename of <file>.
+       multiple files.  The path of the file in the archive is built by
+       concatenating the value of the last `--prefix` option (if any)
+       before this `--add-file` and the basename of <file>.

 
 --worktree-attributes::
        Look for attributes in .gitattributes files in the working tree
 
 --worktree-attributes::
        Look for attributes in .gitattributes files in the working tree


@@ -194,6 +196,12 @@ EXAMPLES
        commit on the current branch. Note that the output format is
        inferred by the extension of the output file.
 
        commit on the current branch. Note that the output format is
        inferred by the extension of the output file.
 

+`git archive -o latest.tar --prefix=build/ --add-file=configure --prefix= HEAD`::
+
+       Creates a tar archive that contains the contents of the latest
+       commit on the current branch with no prefix and the untracked
+       file 'configure' with the prefix 'build/'.
+

 `git config tar.tar.xz.command "xz -c"`::
 
        Configure a "tar.xz" format for making LZMA-compressed tarfiles.
 `git config tar.tar.xz.command "xz -c"`::
 
        Configure a "tar.xz" format for making LZMA-compressed tarfiles.