plumbing: transport, add git-upload-archive support by aymanbagabas · Pull Request #1986 · go-git/go-git

aymanbagabas · 2026-04-13T15:01:05Z

This PR adds support for the git-upload-archive service to the transport layer, allowing fetching of archives from remote git repositories over SSH, HTTP, and local file transports.

Background

The git-upload-archive protocol command is used by git archive --remote to fetch archives from remote repositories without cloning them. This is useful for CI/CD pipelines, release automation, and tools that need specific files from a repo.

Changes

Client-Side Types

Archiver interface - Sessions that implement this can perform archive operations:

type Archiver interface {
    Archive(ctx context.Context, req *ArchiveRequest) (io.ReadCloser, error)
}

ArchiveRequest - Client archive request:

Args []string: arguments sent as "argument " pkt-lines (format, prefix, tree-ish, paths)
Progress sideband.Progress: optional progress callback for status messages

Server-Side Types

UploadArchiveRequest - Server archive request configuration:

AllowUnreachable bool: disables security restrictions allowing arbitrary refs

UploadArchive function - Server-side handler for the git-upload-archive protocol.

Backend Support

SSH/TCP/Unix transports - Backend now dispatches to UploadArchive:

case transport.UploadArchiveService:
    return transport.UploadArchive(...)

HTTP - Left for future protocol-v2 work (HTTP archive requires command-based protocol)

Wire Protocol

Implements the git-upload-archive protocol:

Client sends "argument " pkt-lines for format, prefix, tree-ish, etc.
Server sends "ACK" or "NACK "
Archive data streamed via sideband (channel 1 = data, channel 2 = progress)

Supported Formats

Supported formats parsed from args:

tar, tar.gz, tgz, zip
--prefix=path/ adds prefix to archive entries
--list lists available archives
Tree-ish (commit, tag, branch) specifies what to archive

Testing

TestArchive_Tar, TestArchive_TarGz, TestArchive_Zip (file transport)
TestGitTransport_Archive (git daemon transport)
TestSSHTransport_Archive (SSH transport)

All tests verify archive contents against git's output.

Security

The uploadArchive.allowUnreachable config option controls whether arbitrary SHA-1 expressions are allowed. By default, only ref targets (e.g., v1.0, main) and ref:path sub-tree syntax are allowed.

Follow-up Work

A future PR will add porcelain-level support:

git.Archive() convenience method
ArchiveOptions with parametrized fields:
- Format: tar, tar.gz, zip
- Prefix: prefix path for archive entries
- Remote: tree-ish reference to archive
- Paths: optional path filter
- Additional git archive --remote flags

Usage Example

sess, _ := client.Dial("[email protected]:go-git/go-git.git")
req := &transport.ArchiveRequest{
    Args: []string{"--format=tar.gz", "--prefix=go-git/", "v5.12.0"},
}
rc, _ := sess.Archive(ctx, req)
defer rc.Close()
// Write rc to file or pipe to tar/gzip

Supersedes: #1985

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

aymanbagabas · 2026-04-13T15:02:56Z

+	// AllowUnreachable when true disables the default security restrictions
+	// and allows clients to use arbitrary SHA-1 expressions. By default,
+	// only direct ref targets (e.g. v1.0, main) and ref:path sub-tree
+	// syntax (e.g. v1.0:Documentation) are allowed.
+	//
+	// This serves as the default value. When the repository-level config
+	// uploadArchive.allowUnreachable is explicitly set, it always overrides
+	// this value (both true → false and false → true).
+	// See https://git-scm.com/docs/git-upload-archive
+	AllowUnreachable bool


This is usually derived from global/system config then overridden by repository config. Alternatively, we'd use config.LoadConfig.

cc/ @pjbgf

Let's start with the current cfg, err := st.Config() which is already in place. As that's the safest approach to start with.

Cool, I will drop this option and add a comment to investigate this later and derive it from global/system config before repository config.

pjbgf

@aymanbagabas thanks for looking into this, here's some feedback:

pjbgf · 2026-04-14T14:53:15Z

+	// AllowUnreachable when true disables the default security restrictions
+	// and allows clients to use arbitrary SHA-1 expressions. By default,
+	// only direct ref targets (e.g. v1.0, main) and ref:path sub-tree
+	// syntax (e.g. v1.0:Documentation) are allowed.
+	//
+	// This serves as the default value. When the repository-level config
+	// uploadArchive.allowUnreachable is explicitly set, it always overrides
+	// this value (both true → false and false → true).
+	// See https://git-scm.com/docs/git-upload-archive
+	AllowUnreachable bool


Let's start with the current cfg, err := st.Config() which is already in place. As that's the safest approach to start with.

pjbgf · 2026-04-14T22:10:58Z

+	return (mode | 0o777) &^ defaultUmask
+}
+
+func writeTarArchive(st storage.Storer, w io.Writer, tree *object.Tree, prefix string, pathFilter []string, modTime time.Time) error {


I think we are missing this:

Additionally the commit ID is stored in a global extended pax header if the tar format is used; it can be extracted using git get-tar-commit-id. In ZIP files it is stored as a file comment.

Add git-upload-archive service support to transport layer. This allows fetching archives (tarballs) from remote git repositories over various transports (SSH, HTTP, and local file). Expose new Archivable interface via transport.Session and implement: - ArchiveRequest type for archive configuration (format, compression, prefix) - UploadArchiveRequest/UploadArchive types for wire protocol - Support for archive filters (tree and commit filters) - Backend dispatch for SSH/TCP/Unix transports - Tests for file, git, and SSH transports HTTP backend support left for future protocol-v2 work.

The previous implementation was losing file permission details by converting all files to either 0o644 or 0o755, discarding the actual git mode bits including group-writable. Added applyUmask() functions that extract Unix permission bits from the git mode and apply the default umask (0o002) following canonical git's tar.umask behavior. This preserves the original file permissions from the tree being archived. Also added tests to verify file permissions are correctly preserved in both tar and zip archives.

… position for paths

…nd tests

…hive

…at rely on shared fixture state

Signed-off-by: Paulo Gomes <[email protected]>

pjbgf

@aymanbagabas thanks for the great effort putting this together. 🙇🙇🙇

aymanbagabas requested review from Copilot and pjbgf April 13, 2026 15:01

Copilot AI reviewed Apr 13, 2026

View reviewed changes

aymanbagabas commented Apr 13, 2026

View reviewed changes

pjbgf requested changes Apr 14, 2026

View reviewed changes

aymanbagabas force-pushed the transport-archive branch from 73b8fc0 to 174aa08 Compare April 15, 2026 03:20

aymanbagabas requested a review from pjbgf April 15, 2026 03:29

aymanbagabas force-pushed the transport-archive branch 2 times, most recently from 5ef59da to cebfcdd Compare April 16, 2026 00:08

pjbgf reviewed Apr 23, 2026

View reviewed changes

Comment thread internal/archive/archive.go Outdated

aymanbagabas force-pushed the transport-archive branch from 8106cd2 to 6fa62ef Compare April 24, 2026 00:59

aymanbagabas and others added 19 commits April 24, 2026 15:28

plumbing: transport, support space-separated args and respect treeish…

6690d3c

… position for paths

plumbing: transport, drop allowUnreachable option

7b3bb62

plumbing: transport, add comment about git archive with trees

287273b

plumbing: transport, archive: include commit ID in tar/zip archives a…

6f4d3d3

…nd tests

plumbing: transport, archive: add error for pathspec with no matches

e0ea3ae

plumbing: transport, archive: refactor archive code into internal/arc…

47b9e38

…hive

plumbing: archive, add tests for path filter matching and ref resolution

96e9d8b

plumbing: transport, archive: add test cases for nested paths

5e54d82

plumbing: transport, archive: add allowUnreachable security tests

63c1825

internal: archive, fix lint and parallelize tests

7683326

internal: archive, test: suppress parallel test warnings for tests th…

e521fdc

…at rely on shared fixture state

plumbing: transport, add annotated tags support for git-upload-archive

9b69c9c

Signed-off-by: Paulo Gomes <[email protected]>

plumbing: transport, Explicit errors for unsupported archive args

8732362

Signed-off-by: Paulo Gomes <[email protected]>

plumbing: transport, Fix linter issue

fe61e15

Signed-off-by: Paulo Gomes <[email protected]>

plumbing: transport, Remove support for unreachable

7df71e6

Signed-off-by: Paulo Gomes <[email protected]>

plumbing: transport, Reject oversized symlinks

362d653

Signed-off-by: Paulo Gomes <[email protected]>

plumbing: transport, Add prefix validation

4928734

Signed-off-by: Paulo Gomes <[email protected]>

pjbgf force-pushed the transport-archive branch from 6fa62ef to 4928734 Compare April 24, 2026 14:28

plumbing: transport, Handle archive errors

ce1e0f0

Signed-off-by: Paulo Gomes <[email protected]>

pjbgf approved these changes Apr 24, 2026

View reviewed changes

pjbgf merged commit 5b47ae8 into go-git:main Apr 24, 2026
16 checks passed

aymanbagabas mentioned this pull request Apr 24, 2026

git: add repository and remote archive support #2013

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

plumbing: transport, add git-upload-archive support#1986

plumbing: transport, add git-upload-archive support#1986
pjbgf merged 20 commits into
go-git:mainfrom
aymanbagabas:transport-archive

aymanbagabas commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

aymanbagabas Apr 13, 2026

Uh oh!

pjbgf Apr 14, 2026

Uh oh!

aymanbagabas Apr 15, 2026

Uh oh!

pjbgf left a comment

Uh oh!

pjbgf Apr 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pjbgf Apr 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pjbgf left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

aymanbagabas commented Apr 13, 2026

Background

Changes

Client-Side Types

Server-Side Types

Backend Support

Wire Protocol

Supported Formats

Testing

Security

Follow-up Work

Usage Example

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

aymanbagabas Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

pjbgf Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

aymanbagabas Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

pjbgf left a comment

Choose a reason for hiding this comment

Uh oh!

pjbgf Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pjbgf Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pjbgf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants