The pack command

git teleport pack [<options>] [--] [<beamdownfile>]

Generates new outgoing bundle files. A local mirror is created and/or updated for each repository in <beamdownfile>. The mirrors are then packed into bundle files. By default, the bundles will be incremental: that is, they will not contain the commits or refs from previous invocations of pack.

If the Beamdownfile is unspecified, the current working directory is searched.

Generated bundles are output in the bundles/latest directory, which is relative to the Beamdownfile. On symlink-capable platforms, this directory will be a symbolic link.

--full

Generate bundles which contain a complete history. This is useful if the recipient needs a completely fresh copy to resolve unpack issues.

--no-save

Run without saving the incremental history. The next pack will contain the commits which were also packed into these bundles. See "Differential Bundles."

--offline

Run without accessing the network. Local caches of mirrored repositories will not be updated. This permits you to create bundles without network access. Bundling will fail if you do not already have a cache for each mirror, and your bundles may be potentially out-of-date.

Exit Codes

  • 0: bundles successfully created
  • 1: failed to create bundles
  • 2: nothing new to bundle. No bundles were generated.

Environment Variables

  • GTELEPORT_CACHE: caches of mirrored repositories are stored in this location. If left empty, a platform-appropriate storage location is automatically selected.

  • GTELEPORT_BEAMDOWNFILE: an alternative way to specify the Beamdownfile to use.

  • GTELEPORT_MIRROR_REFS: an allowlist of Git refs to pack. Set to a space-delimited list of Git refs to mirror, like

    refs/heads/* refs/tags/* refs/notes/*

    If you wish to bundle more than the default refs, both the sending and receiving side need the same value of GTELEPORT_MIRROR_REFS. You may use negative refs like ^refs/notthis/*, but Git 1.8 does not support them.

    For further reading on refs, see "Git References."

Incremental Bundles

In the standard mode of operation, pack creates incremental bundles. Each bundle excludes everything from all previous bundles. As a result, the receiving side needs to apply all the bundle files, in order. If you run pack at three different times A, B, and C, the receiver must unpack them in order:

git teleport unpack bundles_A "$DEST"
git teleport unpack bundles_B "$DEST"
git teleport unpack bundles_C "$DEST"

  • If the receiving side mistakenly unpacks bundles_C first, the operation will fail.

  • If the receiving side unpacks bundles_A after bundles_B, git-teleport will discard some of the Git history graph. The receiver must unpack B again before proceeding on to C.

This mode is efficient for point-to-point transfers and minimizes storage during the transfer. It is inefficient for one-to-many transfers, however, as receivers are obligated to download and process every pack.

Differential Bundles

In differential bundles, only two packs of bundles ever need to exist at a time:

  1. The first is a --full bundle that contains all history.
  2. The second contains the history from the last --full bundle to "now."

This is optimized for one-to-many transfers. New receivers can obtain the complete history by downloading only two sets of bundles. No matter how far behind a receiver is, it only has to download two bundles. If a receiver misses an update, the next differential bundle will still contain everything they need.

To make differential bundles, first make a "full" bundle with complete history.

git teleport pack --full

Ensure that these bundles are uploaded somewhere to persistent storage. New receive sites may want them.

At a later time,

git teleport pack --no-save

This creates a differential bundle that is relative to your last --full bundle. Upload these bundles alongside your last --full bundle. Receive sites that have already applied the --full bundle only need your --no-save differential bundle.

You can create as many differential bundles as you want. When the differential bundles become "too large" in size to be convenient, make a new --full bundle.

In the future, this mode will be better automated.

For further reading, see "Sending Repositories."