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 [verse]
  12 'git bundle' create <file> [--basis=ref] <git-rev-list args>
  13 'git bundle' verify <file>
  14 'git bundle' list-heads <file> [refname...]
  15 'git bundle' unbundle <file> [refname...]
  16
  17 DESCRIPTION
  18 -----------
  19
  20 Some workflows require that one or more branches of development on one
  21 machine be replicated on another machine, but the two machines cannot
  22 be directly connected so the interactive git protocols (git, ssh,
  23 rsync, http) cannot be used.  This command provides support for
  24 'git-fetch' and 'git-pull' to operate by packaging objects and references
  25 in an archive at the originating machine, then importing those into
  26 another repository using 'git-fetch' and 'git-pull'
  27 after moving the archive by some means (i.e., by sneakernet).  As no
  28 direct connection between repositories exists, the user must specify a
  29 basis for the bundle that is held by the destination repository: the
  30 bundle assumes that all objects in the basis are already in the
  31 destination repository.
  32
  33 OPTIONS
  34 -------
  35
  36 create <file>::
  37        Used to create a bundle named 'file'.  This requires the
  38        'git-rev-list' arguments to define the bundle contents.
  39
  40 verify <file>::
  41        Used to check that a bundle file is valid and will apply
  42        cleanly to the current repository.  This includes checks on the
  43        bundle format itself as well as checking that the prerequisite
  44        commits exist and are fully linked in the current repository.
  45        'git-bundle' prints a list of missing commits, if any, and exits
  46        with non-zero status.
  47
  48 list-heads <file>::
  49        Lists the references defined in the bundle.  If followed by a
  50        list of references, only references matching those given are
  51        printed out.
  52
  53 unbundle <file>::
  54        Passes the objects in the bundle to 'git-index-pack'
  55        for storage in the repository, then prints the names of all
  56        defined references. If a reflist is given, only references
  57        matching those in the given list are printed. This command is
  58        really plumbing, intended to be called only by 'git-fetch'.
  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 'git-fetch-pack').
  76
  77 --basis::
  78        Specify a basis ref that already exists on the remote side. This
  79        allows git-bundle to only write out objects that are newer, thus
  80        saving space.
  81
  82 SPECIFYING REFERENCES
  83 ---------------------
  84
  85 'git-bundle' will only package references that are shown by
  86 'git-show-ref': this includes heads, tags, and remote heads.  References
  87 such as master~1 cannot be packaged, but are perfectly suitable for
  88 defining the basis.  More than one reference may be packaged, and more
  89 than one basis can be specified.  The objects packaged are those not
  90 contained in the union of the given bases.  Each basis can be
  91 specified explicitly (e.g., ^master~10), or implicitly (e.g.,
  92 master~10..master, master --since=10.days.ago).
  93
  94 It is very important that the basis used be held by the destination.
  95 It is okay to err on the side of conservatism, causing the bundle file
  96 to contain objects already in the destination as these are ignored
  97 when unpacking at the destination.
  98
  99 EXAMPLE
 100 -------
 101
 102 Assume two repositories exist as R1 on machine A, and R2 on machine B.
 103 For whatever reason, direct connection between A and B is not allowed,
 104 but we can move data from A to B via some mechanism (CD, email, etc).
 105 We want to update R2 with developments made on branch master in R1.
 106
 107 To create the bundle you have to specify the basis. You have some options:
 108
 109 - Without basis.
 110 +
 111 This is useful when sending the whole history.
 112
 113 ------------
 114 $ git bundle create mybundle master
 115 ------------
 116
 117 - Using temporally tags.
 118 +
 119 We set a tag in R1 (lastR2bundle) after the previous such transport,
 120 and move it afterwards to help build the bundle.
 121
 122 ------------
 123 $ git bundle create mybundle --basis=lastR2bundle master
 124 $ git tag -f lastR2bundle master
 125 ------------
 126
 127 - Using a tag present in both repositories
 128
 129 ------------
 130 $ git bundle create mybundle --basis=v1.0.0 master
 131 ------------
 132
 133 - A basis based on time.
 134
 135 ------------
 136 $ git bundle create mybundle master --since=10.days.ago
 137 ------------
 138
 139 - With a limit on the number of commits
 140
 141 ------------
 142 $ git bundle create mybundle master -n 10
 143 ------------
 144
 145 Then you move mybundle from A to B, and in R2 on B:
 146
 147 ------------
 148 $ git bundle verify mybundle
 149 $ git fetch mybundle master:localRef
 150 ------------
 151
 152 With something like this in the config in R2:
 153
 154 ------------------------
 155 [remote "bundle"]
 156     url = /home/me/tmp/file.bdl
 157     fetch = refs/heads/*:refs/remotes/origin/*
 158 ------------------------
 159
 160 You can first sneakernet the bundle file to ~/tmp/file.bdl and
 161 then these commands on machine B:
 162
 163 ------------
 164 $ git ls-remote bundle
 165 $ git fetch bundle
 166 $ git pull bundle
 167 ------------
 168
 169 would treat it as if it is talking with a remote side over the
 170 network.
 171
 172 Author
 173 ------
 174 Written by Mark Levedahl <mdl123@verizon.net>
 175
 176 GIT
 177 ---
 178 Part of the linkgit:git[1] suite