Skip to content
Tutorials Center
My learning

Topics

Lesson 41 of 78 ยท Remotes and Collaboration

git bundle and git archive

Move Git history without a server with git bundle, and export clean snapshots as zip or tar with git archive: create, verify, clone, fetch, prefixes and export-ignore.

Most Git sharing assumes a network and a server. But sometimes you have neither: a build machine with no internet, an air-gapped network, a USB stick as the only way out, or a client who wants "the code" as a single file. Git has two small commands for these situations. git bundle packs history (commits, branches, tags) into one file that behaves like a remote. git archive packs a snapshot (the files of one commit, with no history and no .git folder) into a zip or tar.

This lesson shows both, with a clear rule for choosing: if the receiver needs to keep working with Git, send a bundle; if they only need the files, send an archive.

Bundles: a remote in a file

A bundle is a normal pack of Git objects plus a header that lists the refs it contains. Because the format is the same one used on the network, you can clone, fetch and pull from a bundle file exactly as if it were a repository.

flowchart LR
  A["Your repository"] -->|"git bundle create"| B["repo.bundle<br/>one file"]
  B -->|"USB stick, email, shared drive"| C["Other machine"]
  C -->|"git clone repo.bundle"| D["Full repository"]

A bundle carries history across a gap where no network exists.

Create one with git bundle create <file> <refs>. Use --all for every branch and tag, or name specific refs.

Bash Create, verify and clone a bundle

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

bundle verify reports that the bundle is okay and has a complete history, and list-heads shows the refs it carries: HEAD, both branches and the tag v1.0. The clone printed all three commits and set origin to the bundle file's path. Checking the remote shows the file as the fetch URL, which is useful: you can git fetch origin later with a newer bundle at the same path.

Incremental bundles

The first bundle contains everything. Later you only want to send what is new. Give git bundle create a revision range that tells it what the receiver already has. The receiver must have the prerequisite commits, otherwise fetch fails; verify tells you which ones are required.

Bash Send only new commits

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The range sent..main means "commits reachable from main but not from sent". The verify output lists the prerequisite commit the receiver must already have; the copy has it, so the check passes. In the copy, git fetch took the new commits straight from the file, and fast-forwarding the local branch brought the working tree up to date. Tags are convenient markers for "what I sent last time". Many teams keep a tag such as last-bundle and move it after each export.

Fetching from a bundle in a repository that lacks the prerequisite fails with a message such as error: Repository lacks these prerequisite commits. That is your cue to send a bigger bundle.

git archive: a snapshot without history

git archive writes the files of a tree to a tar or zip stream. The result has no .git directory, no history, and contains only tracked files, which makes it the right tool for a release tarball, a deployment package or a hand-over to someone who does not use Git.

Bash Zip and tar snapshots with a prefix

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The list shows only tracked files under the proj-1.0/ prefix: the .env file never appears because it was never committed. The extracted app.py shows the committed contents without the later line, because git archive reads from the commit, not from your working directory. Give a path after the tree-ish to export part of the project. -o file.zip picks the format from the extension, and --format=tar.gz and tgz are also available when the system has gzip.

Always use --prefix with a trailing slash. Otherwise unpacking spills files into the current directory. Name any commit, tag or branch instead of HEAD: git archive --format=zip -o release.zip v1.0 packs a past release.

export-ignore and export-subst

You can control what archives contain with .gitattributes. export-ignore leaves matching paths out of archives (tests, CI config, development tooling), and export-subst expands placeholders such as $Format:%H$ with the commit hash.

Bash Trim an archive with export-ignore

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The archive has no tests/ and no .gitattributes, and the archived VERSION file contains the real abbreviated commit hash while the working copy still has the raw placeholder. The attribute rules are read from the commit that is being archived, so commit them first.

Choosing between them

You need Use
The receiver continues with Git (branches, log, blame) git bundle
An offline backup of the full repository git bundle create backup.bundle --all
A source package for a customer, installer or server git archive
A tiny update for an air-gapped clone incremental git bundle
Just one folder or file from an old release git archive <tag> path

Bundles are also handy for backups and for reporting bugs: git bundle create bug.bundle main lets a maintainer reproduce your problem with full history. Both commands are read-only on your repository. For regular network sharing see Remotes and Pushing and Pulling, and for repositories too big to move around see Sparse Checkout and Large Repositories.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A colleague has no network access but needs your whole repository, including history. What do you send?

    A bundle contains the objects and refs, so the receiver can clone or fetch from it. An archive has only a snapshot of files with no history.
  2. 2. Which command packs the files of the v1.0 tag into release.zip, with no history?

    git archive reads a tree-ish (here a tag) and writes only its files. -o picks the output file and the zip format.
  3. 3. What does the range sent..main mean when creating an incremental bundle?

    A..B selects commits in B that are not in A. The receiver must already have A (the prerequisite) for the bundle to be usable.
  4. 4. Why does an archive not contain your untracked .env file or your uncommitted edits?

    git archive exports the tree of the commit you name. Untracked files and unstaged changes are not part of any commit.

Summary

  • git bundle create file --all packs commits, branches and tags into one file; git bundle verify checks it and git clone file or git fetch file uses it like a remote.
  • Incremental bundles use a range such as sent..main; the receiver needs the prerequisite commits.
  • git archive --format=zip|tar -o file <tree-ish> exports a snapshot: no .git, no history, only committed files.
  • Use --prefix=name/ so the archive unpacks into one folder, and a path argument to export part of the project.
  • .gitattributes with export-ignore and export-subst shapes archive contents.
  • Bundle for history, archive for files.

Next: Git Objects