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 24git-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 linkgit:git-fetch[1] and linkgit:git-pull[1] 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 linkgit:git-index-pack[1] 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 59 linkgit:git-fetch[1]. 60 61[git-rev-list-args...]:: 62 A list of arguments, acceptable to git-rev-parse and 63 git-rev-list, that specify the specific objects and references 64 to transport. For example, "master~10..master" causes the 65 current master reference to be packaged along with all objects 66 added since its 10th ancestor commit. There is no explicit 67 limit to the number of references and objects that may be 68 packaged. 69 70 71[refname...]:: 72 A list of references used to limit the references reported as 73 available. This is principally of use to git-fetch, which 74 expects to receive only those references asked for and not 75 necessarily everything in the pack (in this case, git-bundle is 76 acting like linkgit:git-fetch-pack[1]). 77 78SPECIFYING REFERENCES 79--------------------- 80 81git-bundle will only package references that are shown by 82git-show-ref: this includes heads, tags, and remote heads. References 83such as master~1 cannot be packaged, but are perfectly suitable for 84defining the basis. More than one reference may be packaged, and more 85than one basis can be specified. The objects packaged are those not 86contained in the union of the given bases. Each basis can be 87specified explicitly (e.g., ^master~10), or implicitly (e.g., 88master~10..master, master --since=10.days.ago). 89 90It is very important that the basis used be held by the destination. 91It is okay to err on the side of conservatism, causing the bundle file 92to contain objects already in the destination as these are ignored 93when unpacking at the destination. 94 95EXAMPLE 96------- 97 98Assume two repositories exist as R1 on machine A, and R2 on machine B. 99For whatever reason, direct connection between A and B is not allowed, 100but we can move data from A to B via some mechanism (CD, email, etc). 101We want to update R2 with developments made on branch master in R1. 102 103To create the bundle you have to specify the basis. You have some options: 104 105- Without basis. 106+ 107This is useful when sending the whole history. 108 109------------ 110$ git bundle create mybundle master 111------------ 112 113- Using temporally tags. 114+ 115We set a tag in R1 (lastR2bundle) after the previous such transport, 116and move it afterwards to help build the bundle. 117 118------------ 119$ git-bundle create mybundle master ^lastR2bundle 120$ git tag -f lastR2bundle master 121------------ 122 123- Using a tag present in both repositories 124 125------------ 126$ git bundle create mybundle master ^v1.0.0 127------------ 128 129- A basis based on time. 130 131------------ 132$ git bundle create mybundle master --since=10.days.ago 133------------ 134 135- With a limit on the number of commits 136 137------------ 138$ git bundle create mybundle master -n 10 139------------ 140 141Then you move mybundle from A to B, and in R2 on B: 142 143------------ 144$ git-bundle verify mybundle 145$ git-fetch mybundle master:localRef 146------------ 147 148With something like this in the config in R2: 149 150------------------------ 151[remote "bundle"] 152 url = /home/me/tmp/file.bdl 153 fetch = refs/heads/*:refs/remotes/origin/* 154------------------------ 155 156You can first sneakernet the bundle file to ~/tmp/file.bdl and 157then these commands on machine B: 158 159------------ 160$ git ls-remote bundle 161$ git fetch bundle 162$ git pull bundle 163------------ 164 165would treat it as if it is talking with a remote side over the 166network. 167 168Author 169------ 170Written by Mark Levedahl <mdl123@verizon.net> 171 172GIT 173--- 174Part of the linkgit:git[7] suite