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