[PATCH] archive: document that --add-virtual-file takes full path

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

> René Scharfe <l.s.r@web.de> writes:
>
>> I'm not sure I have an opinion on that topic, yet.  Fixing the
>> documentation is certainly easier.  Adding the prefix to the path of
>> virtual files as well is a breaking change.  I feel that the easier
>> route should at least be mentioned in the commit message and why it
>> was not taken.
>
> It has been a few weeks since this discussion stalled.  Let me make
> an executive decision on the direction here---let's keep the behaviour
> and align the documentation so that we won't break existing users.
>
> Thanks.

So here is to re-ignite the discussion.

----- >8 -----
Subject: [PATCH] archive: document that --add-virtual-file takes full path

Tom Scogland noticed that `--add-virtual-file` option uses the path
specified as its value as-is, without prepending any value given to
the `--prefix` option like `--add-file` does.

The behaviour has always been that way since the option was
introduced, but the documentation has always been wrong and said
that it would use the value of `--prefix` just like `--add-file`
does.

We could modify the behaviour to make it literally work like the
documentation said, but it would break existing scripts the users
use.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-archive.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index 98526f2beb..a0e3fe7996 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -53,7 +53,7 @@ OPTIONS
 --prefix=<prefix>/::
 	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` and `--add-virtual-file`.
+	value gets used by `--add-file`.
 
 -o <file>::
 --output=<file>::
@@ -67,9 +67,7 @@ OPTIONS
 
 --add-virtual-file=<path>:<content>::
 	Add the specified contents to the archive.  Can be repeated to add
-	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-virtual-file` and `<path>`.
+	multiple files.
 +
 The `<path>` argument can start and end with a literal double-quote
 character; the contained file name is interpreted as a C-style string,
@@ -81,6 +79,10 @@ if the path begins or ends with a double-quote character.
 The file mode is limited to a regular file, and the option may be
 subject to platform-dependent command-line limits. For non-trivial
 cases, write an untracked file and use `--add-file` instead.
++
+Note that unlike `--add-file` the path created in the archive is not
+affected by the `--prefix` option, as a full `<path>` can be given as
+the value of the option.
 
 --worktree-attributes::
 	Look for attributes in .gitattributes files in the working tree
-- 
2.45.2-683-g09b5b61c39