Documentation/git-bundle.txt

   1 git-bundle(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-bundle - Move objects and refs by archive
   7
   8
   9 SYNOPSIS
  10 --------
  11 'git-bundle' create <file> [git-rev-list args]
  12 'git-bundle' verify <file>
  13 'git-bundle' list-heads <file> [refname...]
  14 'git-bundle' unbundle <file> [refname...]
  15
  16 DESCRIPTION
  17 -----------
  18
  19 Some workflows require that one or more branches of development on one
  20 machine be replicated on another machine, but the two machines cannot
  21 be directly connected so the interactive git protocols (git, ssh,
  22 rsync, http) cannot be used.  This command provides support for
  23 git-fetch and git-pull to operate by packaging objects and references
  24 in an archive at the originating machine, then importing those into
  25 another repository using gitlink:git-fetch[1] and gitlink:git-pull[1]
  26 after moving the archive by some means (i.e., by sneakernet).  As no
  27 direct connection between repositories exists, the user must specify a
  28 basis for the bundle that is held by the destination repository: the
  29 bundle assumes that all objects in the basis are already in the
  30 destination repository.
  31
  32 OPTIONS
  33 -------
  34
  35 create <file>::
  36        Used to create a bundle named 'file'.  This requires the
  37        git-rev-list arguments to define the bundle contents.
  38
  39 verify <file>::
  40        Used to check that a bundle file is valid and will apply
  41        cleanly to the current repository.  This includes checks on the
  42        bundle format itself as well as checking that the prerequisite
  43        commits exist and are fully linked in the current repository.
  44        git-bundle prints a list of missing commits, if any, and exits
  45        with non-zero status.
  46
  47 list-heads <file>::
  48        Lists the references defined in the bundle.  If followed by a
  49        list of references, only references matching those given are
  50        printed out.
  51
  52 unbundle <file>::
  53        Passes the objects in the bundle to gitlink:git-index-pack[1]
  54        for storage in the repository, then prints the names of all
  55        defined references. If a reflist is given, only references
  56        matching those in the given list are printed. This command is
  57        really plumbing, intended to be called only by
  58        gitlink:git-fetch[1].
  59
  60 [git-rev-list-args...]::
  61        A list of arguments, acceptable to git-rev-parse and
  62        git-rev-list, that specify the specific objects and references
  63        to transport.  For example, "master~10..master" causes the
  64        current master reference to be packaged along with all objects
  65        added since its 10th ancestor commit.  There is no explicit
  66        limit to the number of references and objects that may be
  67        packaged.
  68
  69
  70 [refname...]::
  71        A list of references used to limit the references reported as
  72        available. This is principally of use to git-fetch, which
  73        expects to receive only those references asked for and not
  74        necessarily everything in the pack (in this case, git-bundle is
  75        acting like gitlink:git-fetch-pack[1]).
  76
  77 SPECIFYING REFERENCES
  78 ---------------------
  79
  80 git-bundle will only package references that are shown by
  81 git-show-ref: this includes heads, tags, and remote heads.  References
  82 such as master~1 cannot be packaged, but are perfectly suitable for
  83 defining the basis.  More than one reference may be packaged, and more
  84 than one basis can be specified.  The objects packaged are those not
  85 contained in the union of the given bases.  Each basis can be
  86 specified explicitly (e.g., ^master~10), or implicitly (e.g.,
  87 master~10..master, master --since=10.days.ago).
  88
  89 It is very important that the basis used be held by the destination.
  90 It is okay to err on the side of conservatism, causing the bundle file
  91 to contain objects already in the destination as these are ignored
  92 when unpacking at the destination.
  93
  94 EXAMPLE
  95 -------
  96
  97 Assume two repositories exist as R1 on machine A, and R2 on machine B.
  98 For whatever reason, direct connection between A and B is not allowed,
  99 but we can move data from A to B via some mechanism (CD, email, etc).
 100 We want to update R2 with developments made on branch master in R1.
 101 We set a tag in R1 (lastR2bundle) after the previous such transport,
 102 and move it afterwards to help build the bundle.
 103
 104 in R1 on A:
 105 $ git-bundle create mybundle master ^lastR2bundle
 106 $ git tag -f lastR2bundle master
 107
 108 (move mybundle from A to B by some mechanism)
 109
 110 in R2 on B:
 111 $ git-bundle verify mybundle
 112 $ git-fetch mybundle  refspec
 113
 114 where refspec is refInBundle:localRef
 115
 116
 117 Also, with something like this in your config:
 118
 119 [remote "bundle"]
 120     url = /home/me/tmp/file.bdl
 121     fetch = refs/heads/*:refs/remotes/origin/*
 122
 123 You can first sneakernet the bundle file to ~/tmp/file.bdl and
 124 then these commands:
 125
 126 $ git ls-remote bundle
 127 $ git fetch bundle
 128 $ git pull bundle
 129
 130 would treat it as if it is talking with a remote side over the
 131 network.
 132
 133 Author
 134 ------
 135 Written by Mark Levedahl <mdl123@verizon.net>
 136
 137 GIT
 138 ---
 139 Part of the gitlink:git[7] suite