]>
Commit | Line | Data |
---|---|---|
2e0afafe JS |
1 | git-bundle(1) |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-bundle - Move objects and refs by archive | |
7 | ||
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
e448ff87 | 11 | [verse] |
b1889c36 JN |
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...] | |
2e0afafe JS |
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 | |
1d52b026 DM |
22 | be directly connected, and therefore the interactive git protocols (git, |
23 | ssh, rsync, http) cannot be used. This command provides support for | |
ba020ef5 | 24 | 'git-fetch' and 'git-pull' to operate by packaging objects and references |
2e0afafe | 25 | in an archive at the originating machine, then importing those into |
ba020ef5 | 26 | another repository using 'git-fetch' and 'git-pull' |
3c652d16 | 27 | after moving the archive by some means (e.g., by sneakernet). As no |
1d52b026 | 28 | direct connection between the repositories exists, the user must specify a |
2e0afafe JS |
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 | |
ba020ef5 | 38 | 'git-rev-list' arguments to define the bundle contents. |
2e0afafe JS |
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. | |
ba020ef5 | 45 | 'git-bundle' prints a list of missing commits, if any, and exits |
1d52b026 | 46 | with a non-zero status. |
2e0afafe JS |
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>:: | |
ba020ef5 | 54 | Passes the objects in the bundle to 'git-index-pack' |
2e0afafe | 55 | for storage in the repository, then prints the names of all |
1d52b026 DM |
56 | defined references. If a list of references is given, only |
57 | references matching those in the list are printed. This command is | |
ba020ef5 | 58 | really plumbing, intended to be called only by 'git-fetch'. |
2e0afafe JS |
59 | |
60 | [git-rev-list-args...]:: | |
ba020ef5 | 61 | A list of arguments, acceptable to 'git-rev-parse' and |
1d52b026 DM |
62 | 'git-rev-list', that specifies the specific objects and references |
63 | to transport. For example, `master\~10..master` causes the | |
2e0afafe JS |
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 | |
ba020ef5 | 72 | available. This is principally of use to 'git-fetch', which |
20f50f16 | 73 | expects to receive only those references asked for and not |
1d52b026 DM |
74 | necessarily everything in the pack (in this case, 'git-bundle' acts |
75 | like 'git-fetch-pack'). | |
2e0afafe JS |
76 | |
77 | SPECIFYING REFERENCES | |
78 | --------------------- | |
79 | ||
ba020ef5 JN |
80 | 'git-bundle' will only package references that are shown by |
81 | 'git-show-ref': this includes heads, tags, and remote heads. References | |
1d52b026 | 82 | such as `master\~1` cannot be packaged, but are perfectly suitable for |
2e0afafe JS |
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 | |
1d52b026 DM |
86 | specified explicitly (e.g. `^master\~10`), or implicitly (e.g. |
87 | `master\~10..master`, `--since=10.days.ago master`). | |
2e0afafe JS |
88 | |
89 | It is very important that the basis used be held by the destination. | |
1d52b026 DM |
90 | It is okay to err on the side of caution, causing the bundle file |
91 | to contain objects already in the destination, as these are ignored | |
2e0afafe JS |
92 | when unpacking at the destination. |
93 | ||
94 | EXAMPLE | |
95 | ------- | |
96 | ||
8aa7eebf NS |
97 | Assume you want to transfer the history from a repository R1 on machine A |
98 | to another repository R2 on machine B. | |
2e0afafe | 99 | For whatever reason, direct connection between A and B is not allowed, |
1d52b026 DM |
100 | but we can move data from A to B via some mechanism (CD, email, etc.). |
101 | We want to update R2 with development made on the branch master in R1. | |
99d8ea2c | 102 | |
1d52b026 DM |
103 | To bootstrap the process, you can first create a bundle that does not have |
104 | any basis. You can use a tag to remember up to what commit you last | |
105 | processed, in order to make it easy to later update the other repository | |
106 | with an incremental bundle: | |
99d8ea2c | 107 | |
8aa7eebf NS |
108 | ---------------- |
109 | machineA$ cd R1 | |
ffe4da15 | 110 | machineA$ git bundle create file.bundle master |
8aa7eebf NS |
111 | machineA$ git tag -f lastR2bundle master |
112 | ---------------- | |
99d8ea2c | 113 | |
1d52b026 DM |
114 | Then you transfer file.bundle to the target machine B. If you are creating |
115 | the repository on machine B, then you can clone from the bundle as if it | |
116 | were a remote repository instead of creating an empty repository and then | |
117 | pulling or fetching objects from the bundle: | |
99d8ea2c | 118 | |
8aa7eebf | 119 | ---------------- |
ffe4da15 | 120 | machineB$ git clone /home/me/tmp/file.bundle R2 |
8aa7eebf | 121 | ---------------- |
2e0afafe | 122 | |
8aa7eebf | 123 | This will define a remote called "origin" in the resulting repository that |
1d52b026 | 124 | lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will |
8aa7eebf | 125 | have an entry like this: |
2e0afafe | 126 | |
8aa7eebf NS |
127 | ------------------------ |
128 | [remote "origin"] | |
ffe4da15 | 129 | url = /home/me/tmp/file.bundle |
8aa7eebf NS |
130 | fetch = refs/heads/*:refs/remotes/origin/* |
131 | ------------------------ | |
132 | ||
1d52b026 DM |
133 | To update the resulting mine.git repository, you can fetch or pull after |
134 | replacing the bundle stored at /home/me/tmp/file.bundle with incremental | |
135 | updates. | |
8aa7eebf | 136 | |
1d52b026 DM |
137 | After working some more in the original repository, you can create an |
138 | incremental bundle to update the other repository: | |
8aa7eebf NS |
139 | |
140 | ---------------- | |
141 | machineA$ cd R1 | |
ffe4da15 | 142 | machineA$ git bundle create file.bundle lastR2bundle..master |
8aa7eebf NS |
143 | machineA$ git tag -f lastR2bundle master |
144 | ---------------- | |
145 | ||
1d52b026 DM |
146 | You then transfer the bundle to the other machine to replace |
147 | /home/me/tmp/file.bundle, and pull from it. | |
8aa7eebf NS |
148 | |
149 | ---------------- | |
150 | machineB$ cd R2 | |
151 | machineB$ git pull | |
152 | ---------------- | |
99d8ea2c | 153 | |
8aa7eebf | 154 | If you know up to what commit the intended recipient repository should |
1d52b026 | 155 | have the necessary objects, you can use that knowledge to specify the |
8aa7eebf NS |
156 | basis, giving a cut-off point to limit the revisions and objects that go |
157 | in the resulting bundle. The previous example used lastR2bundle tag | |
1d52b026 | 158 | for this purpose, but you can use any other options that you would give to |
8aa7eebf | 159 | the linkgit:git-log[1] command. Here are more examples: |
99d8ea2c | 160 | |
1d52b026 | 161 | You can use a tag that is present in both: |
99d8ea2c | 162 | |
8aa7eebf NS |
163 | ---------------- |
164 | $ git bundle create mybundle v1.0.0..master | |
165 | ---------------- | |
2e0afafe | 166 | |
1d52b026 | 167 | You can use a basis based on time: |
ee8245b5 | 168 | |
8aa7eebf NS |
169 | ---------------- |
170 | $ git bundle create mybundle --since=10.days master | |
171 | ---------------- | |
2e0afafe | 172 | |
1d52b026 | 173 | You can use the number of commits: |
2e0afafe | 174 | |
8aa7eebf NS |
175 | ---------------- |
176 | $ git bundle create mybundle -10 master | |
177 | ---------------- | |
178 | ||
179 | You can run `git-bundle verify` to see if you can extract from a bundle | |
1d52b026 | 180 | that was created with a basis: |
8aa7eebf NS |
181 | |
182 | ---------------- | |
b1889c36 | 183 | $ git bundle verify mybundle |
8aa7eebf | 184 | ---------------- |
2e0afafe | 185 | |
8aa7eebf | 186 | This will list what commits you must have in order to extract from the |
1d52b026 | 187 | bundle and will error out if you do not have them. |
2e0afafe | 188 | |
8aa7eebf | 189 | A bundle from a recipient repository's point of view is just like a |
1d52b026 DM |
190 | regular repository which it fetches or pulls from. You can, for example, map |
191 | references when fetching: | |
2e0afafe | 192 | |
8aa7eebf NS |
193 | ---------------- |
194 | $ git fetch mybundle master:localRef | |
195 | ---------------- | |
2e0afafe | 196 | |
1d52b026 | 197 | You can also see what references it offers. |
2e0afafe | 198 | |
8aa7eebf NS |
199 | ---------------- |
200 | $ git ls-remote mybundle | |
201 | ---------------- | |
2e0afafe JS |
202 | |
203 | Author | |
204 | ------ | |
205 | Written by Mark Levedahl <mdl123@verizon.net> | |
206 | ||
207 | GIT | |
208 | --- | |
9e1f0a85 | 209 | Part of the linkgit:git[1] suite |