From: René Scharfe Date: Fri, 27 May 2022 17:02:09 GMT Subject: Re: [PATCH v6 1/7] archive: optionally add "virtual" files Message-ID: <71ae5983-6ef8-fe28-46ab-1675e819ce8b@web.de> In-Reply-To: Am 26.05.22 um 22:16 schrieb Junio C Hamano: > René Scharfe writes: > >> 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=/:: >> - Prepend / to each filename in the archive. >> + Prepend / to each filename in the archive. Can be >> + specified multiple times; the last one seen when reading from >> + left to right is applied. > > That can be read to mean that we will use C consistently, > > $ cmd --prefix=A other-args --prefix=B other-args --prefix=C other-args > > which was what I am worried to be a source of confusion. > >> -o :: >> --output=:: >> @@ -58,8 +60,8 @@ OPTIONS >> --add-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 . >> + by concatenating the current value for `--prefix` (if any) and >> + the basename of . > > "the current value for `--prefix` (if any)" would work well once we > somehow make the reader form a mental model that there is "the > current" for the "prefix", which starts with an empty string, and > gets updated every time the "--prefix=/" option is given. Right, "current" has a well-known meaning, but its not enough to convey that the non-standard concept of capturing option values in the middle of the argument list is used here. > > So, perhaps with > > --prefix=/:: > The paths of the files in the tree being archived, > and untracked contents added via the `--add-file` > and `--add-virtual-file` options, can be modified by > prepending the "prefix" value that is in effect when > these options or the tree object is seen on the > command line. The "prefix" value initially starts > as an empty string, and it gets updated every time > this option is given on the command line. > > or something like that, with something like > >> + by concatenating the current value for "prefix" (see `--prefix` >> + above) and the basename of . > > here, it might make it less misunderstanding-prone, hopefully? So how about this, which avoids mentioning the idea of a "current" option, or of updating its value (which implies an order that might not be obvious)? --- >8 --- Subject: [PATCH v2] archive: improve documentation of --prefix Document the interaction between --add-file and --prefix by giving an example. Signed-off-by: René Scharfe --- Documentation/git-archive.txt | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index bc4e76a783..9c0e306c03 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -49,7 +49,9 @@ OPTIONS Report progress to stderr. --prefix=/:: - Prepend / to each filename in the archive. + Prepend / to paths in the archive. Can be repeated; its + leftmost value is used for all tracked files. See below which + value gets used by `--add-file`. -o :: --output=:: @@ -58,8 +60,9 @@ OPTIONS --add-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 . + by concatenating the value of the leftmost `--prefix` option to + the right of this `--add-file` (if any) and the basename of + . --worktree-attributes:: Look for attributes in .gitattributes files in the working tree @@ -194,6 +197,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