The unpack command

git teleport unpack [--] [<beamupfile>] <dest_prefix>

Reads incoming git-teleport bundles from <beamupfile> and mirrors their contents to Git repositories at <dest_prefix>. The <dest_prefix> must be an URL or filename prefix.

If you have just un-archived a collection of bundle files in ~/Downloads/latest, and the root directory on your server for these repositories is /net/mirrors/pub/, then run

git teleport unpack \
    ~/Downloads/latest \
    /net/mirrors/pub/

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

It is safe to unpack the same Beamupfile multiple times—but only if those bundles are the most recent available. See "Precautions" and "Troubleshooting."

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_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."

Required URL Prefix

git-teleport will only unpack into repository URLs which have a path component named "mirror" or "mirrors" exactly. For example,

git@mygitlab:mirrors/intranet/
https://mygitlab/mirror/extranet/
/net/mirrors/pub/

are all valid URL prefixes.

You should also create subdirectories, like intranet, to separate mirrors received from different sources.

The URL prefix is optional for repositories created with skeleton and shared on a local filesystem. The prefix is required for network protocols, like https.

STORE ONLY MIRRORS in this URL prefix. Otherwise, git-teleport may inadvertently overwrite your original projects and commits.

Destination Mirror Not Found?

If any of the repositories specified in the Beamupfile do not exist, the unpack command will report an error like:

error: destination mirror "/net/mirrors/pub/foo/bar.git" not found

The unpack command requires that each entry in the Beamupfile have a matching repository under your selected <dest_prefix>. If your Beamupfile contains an entry named:

# GIT-TELEPORT BEAMUPFILE

foo/bar.git

then you must create an empty repository named "foo/bar.git." The name must match exactly, including case. The .git extension is optional but is highly encouraged.

If your mirrors reside on your local filesystem, you can create a new repository with skeleton. After creating all necessary repositories, run unpack again.

Precautions

The unpack command does not check that the bundles you are attempting to unpack are the most current version.

Incremental bundles—which are the default mode of operation—must be unpacked in the proper order. Every set of bundles that the sending side packs must be unpacked in the same order. To determine the order, use the datestamp on the bundle directory.

If an outdated bundle file is inadvertently unpacked, your mirrors will be forcibly overwritten with an outdated set of refs. To correct this condition, unpack more recent bundle files in the correct order.

For further reading, see "Receiving Repositories" and "Troubleshooting."