Am 26.05.22 um 19:10 schrieb Junio C Hamano: > René Scharfe <l.s.r@xxxxxx> writes: > >> If the prefix is applied then a prefix-less extra file can by had by >> using --prefix= or --no-prefix for it and --prefix=... for the tree, >> e.g.: >> >> $ git archive --add-file=extra --prefix=dir/ v2.36.0 >> >> puts "extra" at the root and the rest under "dir". The order of >> arguments matters here, and the default prefix is the empty string. > > This was the part of the design for the original "--add-file" that I > was moderately unhappy with. If "--add-file" were the only feature > that used "--prefix", I wouldn't have been unhappy, but this rule: > > The value of "--prefix" most recently seen at the point of > "--add-file" is prepended. (By the way, it is not clearly > documented what happens when you give multiple prefix and > when you give prefix before or after add-file) Regarding documentation: I wonder what's missing; a guess is below. > > makes the original use of "--prefix": > > The value given to "--prefix" is prepended to each filename > in the archive. (IOW "git archive --prefix=git-2.36.0/ > v2.36.0" is a way to prefix each and every path in the > tree-ish with the given prefix) > > confusing. Does > > git archive --prefix=bonus-files/ --add-file=extra v2.36.0 > > place the main part of the archive also in bonus-files/ or at the > top level? One reasonable interpretation is "yes", if we imagine > that each invocation of --add-file will consume and reset the prefix. > Another reasonable interpretation is "no", if we imagine that the > prefix last specified will stay around and equally affect both extra > ones and main part of the archive. > > Unfortunately what the implmentation does is the latter, and those > who want to put the main part of the archive at the top-level must > add "--prefix=''" at the end (before the tree-ish). A one-shot --prefix would be surprising -- usually options keep their value until they are specified again with a different value or negated (--no-...). That surprise could be documented away by using a different name like --next-prefix or --single-use-prefix. But a sub-option to a single option like that would probably be better baked into that option, e.g. allow --add-file=<path_in_archive>:<path_in_fs>. > > Because of this potential for confusion ... > >> So extra files can be put anywhere even if --prefix is honored. >> >> Keeping the whole path from --add-virtual-file makes sense to me; I >> slightly prefer applying --prefix on top of that for consistency. > > ... I was hoping that we can releave users from having to worry > about the interaction between "prefix" and contents coming from > outside the tree-ish by ignoring the "prefix". > > But either is fine by me. The unusual thing about the current --prefix implementation is that its current value is captured along the way instead of just using its right-most value. Not sure ignoring it for one of the three archive content sources helps. (Really, it's hard for me to put me in the shoes of someone who doesn't know how these options are supposed to be used.) --- >8 --- Subject: [PATCH] archive: improve documentation of --prefix Document the interaction between --add-file and --prefix by giving an example. Signed-off-by: René Scharfe <l.s.r@xxxxxx> --- Documentation/git-archive.txt | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index bc4e76a783..10a48ab5f8 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -49,7 +49,9 @@ OPTIONS Report progress to stderr. --prefix=<prefix>/:: - Prepend <prefix>/ to each filename in the archive. + Prepend <prefix>/ to each filename in the archive. Can be + specified multiple times; the last one seen when reading from + left to right is applied. -o <file>:: --output=<file>:: @@ -58,8 +60,8 @@ OPTIONS --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>. + by concatenating the current value for `--prefix` (if any) and + the basename of <file>. --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. +`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. -- 2.35.3
