[RFC] archive: behavior of --prefix with absolute or parent path components

[RFC] archive: behavior of --prefix with absolute or parent path components

[Pushkar Singh]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1243 bytes --]

Hi,

While experimenting with "git archive", I noticed some behavior around
the --prefix option that might be worth clarifying.

Currently, --prefix accepts values such as absolute paths or ones with ..,
e.g.:
    git archive --prefix=/ HEAD > out.tar
    git archive --prefix=//// HEAD > out.tar
    git archive --prefix=../../ HEAD > out.tar

Upon listing the archive contents (e.g., tar -tf), you get entries like:
    /a.txt
    ////a.txt
    ../../a.txt

In such cases, tar emits warnings like:
    "Removing leading '/' from member names"
    "Removing leading '../' from member names"

This suggests that Git passes the prefix through as-is, relying on 
downstream tools to sanitize potentially unsafe paths.

From a user perspective, I was wondering:
  - Is this behavior intentional (i.e., leaving validation to archive
    consumers)?
  - Would it be worth documenting this explicitly?
  - Or should there be any normalization or validation at the Git level?

I understand that Git generally avoids enforcing policy decisions in 
such cases, but I wanted to confirm whether this behavior is intentional.

I’d appreciate any thoughts on this :-)

Thanks,
Pushkar

Re: [RFC] archive: behavior of --prefix with absolute or parent path components

[Jeff King]

On Tue, Apr 07, 2026 at 04:21:01PM +0000, Pushkar Singh wrote:

> Currently, --prefix accepts values such as absolute paths or ones with ..,
> e.g.:
>     git archive --prefix=/ HEAD > out.tar
>     git archive --prefix=//// HEAD > out.tar
>     git archive --prefix=../../ HEAD > out.tar
> 
> Upon listing the archive contents (e.g., tar -tf), you get entries like:
>     /a.txt
>     ////a.txt
>     ../../a.txt
> 
> In such cases, tar emits warnings like:
>     "Removing leading '/' from member names"
>     "Removing leading '../' from member names"

Yes, but note that with "-P" tar will happily allow those paths. They
_can_ be useful, if you know what you are doing, but they aren't
necessarily safe when coming from untrusted sources.

We can also generate zip files, but I think most unzip implementations
have similar restrictions (info-zip does, with "-:" to override).

In theory we could support other formats, but after 20 years I don't
think anybody has bothered to do so. Cpio, anyone? :)

Though speaking of cpio (the command, not the format), it will happily
list and extract the paths above from a tar input without any extra
option (it has an option to restrict, but unlike tar, it defaults to
off).

> From a user perspective, I was wondering:
>   - Is this behavior intentional (i.e., leaving validation to archive
>     consumers)?
>   - Would it be worth documenting this explicitly?
>   - Or should there be any normalization or validation at the Git level?
> 
> I understand that Git generally avoids enforcing policy decisions in 
> such cases, but I wanted to confirm whether this behavior is intentional.

I don't recall it ever being discussed. Of the three you mentioned,
"../" and leading "/" are potentially useful, so I don't think we'd want
to disallow them entirely. At least some tar implementations require
"-P" on the generating side to avoid mistakes, so we could follow that
path.  It may be considered a regression by anybody who is using the
feature currently, though.

The "////" is meaningless AFAICT, and could be replaced with a single
slash. But I think it's also mostly harmless, as the reading side (well,
the kernel) will equate "foo/////file" and "foo/file". I don't know if
there are systems where that would not be the case.

So...yeah. I guess we can document it more explicitly. Since you seem to
be the first to ask about it, it does not seem like a common question.
But if we can clarify the behavior without making the current docs
harder to read, I don't see a problem in doing so.

-Peff

Re: [RFC] archive: behavior of --prefix with absolute or parent path components

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

>> In such cases, tar emits warnings like:
>>     "Removing leading '/' from member names"
>>     "Removing leading '../' from member names"
>
> Yes, but note that with "-P" tar will happily allow those paths. They
> _can_ be useful, if you know what you are doing, but they aren't
> necessarily safe when coming from untrusted sources.
>
> We can also generate zip files, but I think most unzip implementations
> have similar restrictions (info-zip does, with "-:" to override).
>
> In theory we could support other formats, but after 20 years I don't
> think anybody has bothered to do so. Cpio, anyone? :)
>
> Though speaking of cpio (the command, not the format), it will happily
> list and extract the paths above from a tar input without any extra
> option (it has an option to restrict, but unlike tar, it defaults to
> off).
>
>> From a user perspective, I was wondering:
>>   - Is this behavior intentional (i.e., leaving validation to archive
>>     consumers)?
>>   - Would it be worth documenting this explicitly?
>>   - Or should there be any normalization or validation at the Git level?
>> 
>> I understand that Git generally avoids enforcing policy decisions in 
>> such cases, but I wanted to confirm whether this behavior is intentional.
>
> I don't recall it ever being discussed. Of the three you mentioned,
> "../" and leading "/" are potentially useful, so I don't think we'd want
> to disallow them entirely. At least some tar implementations require
> "-P" on the generating side to avoid mistakes, so we could follow that
> path.  It may be considered a regression by anybody who is using the
> feature currently, though.

Thanks.  I was writing almost exactly the same message ;-)

> The "////" is meaningless AFAICT, and could be replaced with a single
> slash. But I think it's also mostly harmless, as the reading side (well,
> the kernel) will equate "foo/////file" and "foo/file". I don't know if
> there are systems where that would not be the case.
>
> So...yeah. I guess we can document it more explicitly. Since you seem to
> be the first to ask about it, it does not seem like a common question.
> But if we can clarify the behavior without making the current docs
> harder to read, I don't see a problem in doing so.

Yup, in other words, "Patches welcome".

Re: [RFC] archive: behavior of --prefix with absolute or parent path components

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 2197 bytes --]

On 2026-04-07 at 19:24:54, Jeff King wrote:
> Yes, but note that with "-P" tar will happily allow those paths. They
> _can_ be useful, if you know what you are doing, but they aren't
> necessarily safe when coming from untrusted sources.
> 
> We can also generate zip files, but I think most unzip implementations
> have similar restrictions (info-zip does, with "-:" to override).

I suspect there are people using this with `/` because they want to
deploy files to places like `/etc`.  We've actually had requests for the
ability to have multiple roots in a repository so that people can do
this kind of thing, so I'm certain there are people finding _some_ way
to do it, even if not with this exact approach.

In conjunction with a tool like mtree(1) to adjust ownership and
permissions, this could be useful.

> In theory we could support other formats, but after 20 years I don't
> think anybody has bothered to do so. Cpio, anyone? :)

cpio doesn't have the long filename support that our pax (tar) archives
have, so I wouldn't recommend adding it.  The only place I still see
people use it is initramfs images for Linux.

> I don't recall it ever being discussed. Of the three you mentioned,
> "../" and leading "/" are potentially useful, so I don't think we'd want
> to disallow them entirely. At least some tar implementations require
> "-P" on the generating side to avoid mistakes, so we could follow that
> path.  It may be considered a regression by anybody who is using the
> feature currently, though.
> 
> The "////" is meaningless AFAICT, and could be replaced with a single
> slash. But I think it's also mostly harmless, as the reading side (well,
> the kernel) will equate "foo/////file" and "foo/file". I don't know if
> there are systems where that would not be the case.

Technically, POSIX allows `//` to be different than `/`, I believe,
although I'm not aware of anyone outside of Windows (and maybe Interix)
where that has any special meaning.  If you have such a system, it could
be useful to provide that as well as `/`.

I agree that it's more likely a typo, though.
-- 
brian m. carlson (they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 325 bytes --]

[PATCH] archive: document --prefix handling of absolute and parent paths

[Pushkar Singh]

Clarify that --prefix is used as given and is not normalized,
and may include leading slashes or parent directory components.

Signed-off-by: Pushkar Singh <pushkarkumarsingh1970@gmail.com>
---
 Documentation/git-archive.adoc | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/git-archive.adoc b/Documentation/git-archive.adoc
index a0e3fe7996..086bade6d8 100644
--- a/Documentation/git-archive.adoc
+++ b/Documentation/git-archive.adoc
@@ -54,6 +54,11 @@ OPTIONS
 	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`.
++
+The <prefix> is used as given and is not normalized. It may
+include leading slashes or parent directory components (e.g.,
+`../`). Some archive consumers may treat such paths as
+potentially unsafe and adjust or warn during extraction.
 
 -o <file>::
 --output=<file>::
-- 
2.53.0.582.gca1db8a0f7

Re: [PATCH] archive: document --prefix handling of absolute and parent paths

[Jeff King]

On Wed, Apr 08, 2026 at 04:00:06PM +0000, Pushkar Singh wrote:

>  	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`.
> ++
> +The <prefix> is used as given and is not normalized. It may
> +include leading slashes or parent directory components (e.g.,
> +`../`). Some archive consumers may treat such paths as
> +potentially unsafe and adjust or warn during extraction.

Thanks, this reads fine to me.

-Peff