archive: document that --add-virtual-file takes full path

Commit Message

Junio C Hamano June 14, 2024, 6:40 p.m. UTC

Junio C Hamano <[e-mail]> writes:

> René Scharfe <[e-mail]> 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 <[e-mail]>
---
 Documentation/git-archive.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

Comments

Junio C Hamano June 25, 2024, 10:43 p.m. UTC | #1

Junio C Hamano <[e-mail]> writes:

>> 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

And it seems that nobody is interested in the topic all that much
anymore?

I've read the updated text once again, and didn't see anything
glaringly wrong, so I'll mark it for 'next'.

Thanks.

René Scharfe June 26, 2024, 7:05 p.m. UTC | #2

Am 26.06.24 um 00:43 schrieb Junio C Hamano:
> Junio C Hamano <[e-mail]> writes:
>
>>> 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
>
> And it seems that nobody is interested in the topic all that much
> anymore?

I'm low-key pleased to see a documentation bug being stomped.

Perhaps this saps the energy out of efforts to make --add-virtual-file
respect --prefix, but we'd probably need a new option name for that
anyway to keep backward compatibility (--add-prefix-file?), so the patch
adds no technical obstacle for that at least.

> I've read the updated text once again, and didn't see anything
> glaringly wrong, so I'll mark it for 'next'.

The patch looks good to me.  I like the new paragraph about --prefix not
being respected, in particular because I wouldn't thought of adding it,
but it does look helpful.

Perhaps add a Reported-by: line for Tom that's findable with trailer
tooling, though?

René

Patch

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