Troubleshooting: Things Which Can Go Wrong

  • If the sending side added a new repository, the unpack will fail. Create the missing repository and run the unpack step again. The unpack command is safe to re-run.

  • If you have multiple updates to apply at once—perhaps because you let them accumulate without applying them—be sure to apply them in the order in which they were generated. Otherwise, the unpack will fail.

  • If a bundle won't apply, run git bundle verify on the bundle file. Determine the commits you are missing. You will probably need the sender to generate new bundles. You can:

    • Force full bundles to be generated with git teleport pack --full; OR

    • Revert the Mirror Set (on the sending side) to a previous version and try normal incremental bundles again.

    • Have the sender check and be sure that the bundle contains the required commit(s)

  • Whenever git-teleport needs to fetch or push to a remote repository, it caches it locally. On linux, caches are stored in ~/.cache/git-teleport/. Cache files are transient, and you may delete them to save space.

  • By default, git-teleport will mirror all branches, tags, and notes—but nothing else. This is because some repo hosts, like Gitlab and Github, use extra "read only" refs to pin certain commits and/or store other information. Since these refs are not useful, they are excluded.

    • You may adjust what is mirrored by setting the GTELEPORT_MIRROR_REFS environment variable.

    • This variable must be set on both the sending and receiving side.

  • Git-teleport generates two different bundle files: the incremental update (.bundle) and the refs bundle (.bundle.refs). The first bundle is used to update changed refs. The second is used to delete (or "prune," as git calls it) refs which are no longer in the source repository. If git-teleport fails to generate a refs bundle, it will print a warning and continue. If you see this warning, please report this as a bug.