]>
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] |
c5aecfc8 | 12 | 'git bundle' create [-q | --quiet | --progress | --all-progress] [--all-progress-implied] |
13 | [--version=<version>] <file> <git-rev-list-args> | |
e0eba649 | 14 | 'git bundle' verify [-q | --quiet] <file> |
62b4698e ŠN |
15 | 'git bundle' list-heads <file> [<refname>...] |
16 | 'git bundle' unbundle <file> [<refname>...] | |
2e0afafe JS |
17 | |
18 | DESCRIPTION | |
19 | ----------- | |
20 | ||
21 | Some workflows require that one or more branches of development on one | |
22 | machine be replicated on another machine, but the two machines cannot | |
2de9b711 | 23 | be directly connected, and therefore the interactive Git protocols (git, |
0e40a73a PO |
24 | ssh, http) cannot be used. |
25 | ||
26 | The 'git bundle' command packages objects and references in an archive | |
27 | at the originating machine, which can then be imported into another | |
28 | repository using 'git fetch', 'git pull', or 'git clone', | |
29 | after moving the archive by some means (e.g., by sneakernet). | |
30 | ||
31 | As no | |
1d52b026 | 32 | direct connection between the repositories exists, the user must specify a |
2e0afafe JS |
33 | basis for the bundle that is held by the destination repository: the |
34 | bundle assumes that all objects in the basis are already in the | |
35 | destination repository. | |
36 | ||
37 | OPTIONS | |
38 | ------- | |
39 | ||
79862b6b | 40 | create [options] <file> <git-rev-list-args>:: |
a6190565 | 41 | Used to create a bundle named 'file'. This requires the |
0e40a73a | 42 | '<git-rev-list-args>' arguments to define the bundle contents. |
79862b6b RJ |
43 | 'options' contains the options specific to the 'git bundle create' |
44 | subcommand. | |
2e0afafe JS |
45 | |
46 | verify <file>:: | |
a6190565 MG |
47 | Used to check that a bundle file is valid and will apply |
48 | cleanly to the current repository. This includes checks on the | |
49 | bundle format itself as well as checking that the prerequisite | |
50 | commits exist and are fully linked in the current repository. | |
51 | 'git bundle' prints a list of missing commits, if any, and exits | |
52 | with a non-zero status. | |
2e0afafe JS |
53 | |
54 | list-heads <file>:: | |
a6190565 MG |
55 | Lists the references defined in the bundle. If followed by a |
56 | list of references, only references matching those given are | |
57 | printed out. | |
2e0afafe JS |
58 | |
59 | unbundle <file>:: | |
a6190565 MG |
60 | Passes the objects in the bundle to 'git index-pack' |
61 | for storage in the repository, then prints the names of all | |
62 | defined references. If a list of references is given, only | |
63 | references matching those in the list are printed. This command is | |
64 | really plumbing, intended to be called only by 'git fetch'. | |
2e0afafe | 65 | |
5e1f9605 | 66 | <git-rev-list-args>:: |
a6190565 | 67 | A list of arguments, acceptable to 'git rev-parse' and |
469bfc96 | 68 | 'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES |
1884df1a | 69 | below), that specifies the specific objects and references |
6cf378f0 | 70 | to transport. For example, `master~10..master` causes the |
a6190565 MG |
71 | current master reference to be packaged along with all objects |
72 | added since its 10th ancestor commit. There is no explicit | |
73 | limit to the number of references and objects that may be | |
74 | packaged. | |
2e0afafe JS |
75 | |
76 | ||
62b4698e | 77 | [<refname>...]:: |
a6190565 MG |
78 | A list of references used to limit the references reported as |
79 | available. This is principally of use to 'git fetch', which | |
80 | expects to receive only those references asked for and not | |
81 | necessarily everything in the pack (in this case, 'git bundle' acts | |
82 | like 'git fetch-pack'). | |
2e0afafe | 83 | |
79862b6b RJ |
84 | --progress:: |
85 | Progress status is reported on the standard error stream | |
86 | by default when it is attached to a terminal, unless -q | |
87 | is specified. This flag forces progress status even if | |
88 | the standard error stream is not directed to a terminal. | |
89 | ||
90 | --all-progress:: | |
91 | When --stdout is specified then progress report is | |
92 | displayed during the object count and compression phases | |
93 | but inhibited during the write-out phase. The reason is | |
94 | that in some cases the output stream is directly linked | |
95 | to another command which may wish to display progress | |
96 | status of its own as it processes incoming pack data. | |
97 | This flag is like --progress except that it forces progress | |
98 | report for the write-out phase as well even if --stdout is | |
99 | used. | |
100 | ||
101 | --all-progress-implied:: | |
102 | This is used to imply --all-progress whenever progress display | |
103 | is activated. Unlike --all-progress this flag doesn't actually | |
104 | force any progress display by itself. | |
105 | ||
c5aecfc8 | 106 | --version=<version>:: |
107 | Specify the bundle version. Version 2 is the older format and can only be | |
108 | used with SHA-1 repositories; the newer version 3 contains capabilities that | |
109 | permit extensions. The default is the oldest supported format, based on the | |
110 | hash algorithm in use. | |
111 | ||
79862b6b RJ |
112 | -q:: |
113 | --quiet:: | |
114 | This flag makes the command not to report its progress | |
115 | on the standard error stream. | |
116 | ||
2e0afafe JS |
117 | SPECIFYING REFERENCES |
118 | --------------------- | |
119 | ||
0b444cdb TR |
120 | 'git bundle' will only package references that are shown by |
121 | 'git show-ref': this includes heads, tags, and remote heads. References | |
6cf378f0 | 122 | such as `master~1` cannot be packaged, but are perfectly suitable for |
2e0afafe JS |
123 | defining the basis. More than one reference may be packaged, and more |
124 | than one basis can be specified. The objects packaged are those not | |
125 | contained in the union of the given bases. Each basis can be | |
6cf378f0 JK |
126 | specified explicitly (e.g. `^master~10`), or implicitly (e.g. |
127 | `master~10..master`, `--since=10.days.ago master`). | |
2e0afafe JS |
128 | |
129 | It is very important that the basis used be held by the destination. | |
1d52b026 DM |
130 | It is okay to err on the side of caution, causing the bundle file |
131 | to contain objects already in the destination, as these are ignored | |
2e0afafe JS |
132 | when unpacking at the destination. |
133 | ||
0e40a73a PO |
134 | `git clone` can use any bundle created without negative refspecs |
135 | (e.g., `new`, but not `old..new`). | |
136 | If you want to match `git clone --mirror`, which would include your | |
137 | refs such as `refs/remotes/*`, use `--all`. | |
138 | If you want to provide the same set of refs that a clone directly | |
139 | from the source repository would get, use `--branches --tags` for | |
140 | the `<git-rev-list-args>`. | |
141 | ||
76a8788c NTND |
142 | EXAMPLES |
143 | -------- | |
2e0afafe | 144 | |
8aa7eebf NS |
145 | Assume you want to transfer the history from a repository R1 on machine A |
146 | to another repository R2 on machine B. | |
2e0afafe | 147 | For whatever reason, direct connection between A and B is not allowed, |
1d52b026 DM |
148 | but we can move data from A to B via some mechanism (CD, email, etc.). |
149 | We want to update R2 with development made on the branch master in R1. | |
99d8ea2c | 150 | |
1d52b026 DM |
151 | To bootstrap the process, you can first create a bundle that does not have |
152 | any basis. You can use a tag to remember up to what commit you last | |
153 | processed, in order to make it easy to later update the other repository | |
154 | with an incremental bundle: | |
99d8ea2c | 155 | |
8aa7eebf NS |
156 | ---------------- |
157 | machineA$ cd R1 | |
ffe4da15 | 158 | machineA$ git bundle create file.bundle master |
8aa7eebf NS |
159 | machineA$ git tag -f lastR2bundle master |
160 | ---------------- | |
99d8ea2c | 161 | |
b5fb4770 JH |
162 | Then you transfer file.bundle to the target machine B. Because this |
163 | bundle does not require any existing object to be extracted, you can | |
164 | create a new repository on machine B by cloning from it: | |
99d8ea2c | 165 | |
8aa7eebf | 166 | ---------------- |
ded6aa6b | 167 | machineB$ git clone -b master /home/me/tmp/file.bundle R2 |
8aa7eebf | 168 | ---------------- |
2e0afafe | 169 | |
8aa7eebf | 170 | This will define a remote called "origin" in the resulting repository that |
1d52b026 | 171 | lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will |
8aa7eebf | 172 | have an entry like this: |
2e0afafe | 173 | |
8aa7eebf NS |
174 | ------------------------ |
175 | [remote "origin"] | |
ffe4da15 | 176 | url = /home/me/tmp/file.bundle |
8aa7eebf NS |
177 | fetch = refs/heads/*:refs/remotes/origin/* |
178 | ------------------------ | |
179 | ||
1d52b026 DM |
180 | To update the resulting mine.git repository, you can fetch or pull after |
181 | replacing the bundle stored at /home/me/tmp/file.bundle with incremental | |
182 | updates. | |
8aa7eebf | 183 | |
1d52b026 DM |
184 | After working some more in the original repository, you can create an |
185 | incremental bundle to update the other repository: | |
8aa7eebf NS |
186 | |
187 | ---------------- | |
188 | machineA$ cd R1 | |
ffe4da15 | 189 | machineA$ git bundle create file.bundle lastR2bundle..master |
8aa7eebf NS |
190 | machineA$ git tag -f lastR2bundle master |
191 | ---------------- | |
192 | ||
1d52b026 DM |
193 | You then transfer the bundle to the other machine to replace |
194 | /home/me/tmp/file.bundle, and pull from it. | |
8aa7eebf NS |
195 | |
196 | ---------------- | |
197 | machineB$ cd R2 | |
198 | machineB$ git pull | |
199 | ---------------- | |
99d8ea2c | 200 | |
8aa7eebf | 201 | If you know up to what commit the intended recipient repository should |
1d52b026 | 202 | have the necessary objects, you can use that knowledge to specify the |
8aa7eebf | 203 | basis, giving a cut-off point to limit the revisions and objects that go |
5e1f9605 | 204 | in the resulting bundle. The previous example used the lastR2bundle tag |
1d52b026 | 205 | for this purpose, but you can use any other options that you would give to |
8aa7eebf | 206 | the linkgit:git-log[1] command. Here are more examples: |
99d8ea2c | 207 | |
1d52b026 | 208 | You can use a tag that is present in both: |
99d8ea2c | 209 | |
8aa7eebf NS |
210 | ---------------- |
211 | $ git bundle create mybundle v1.0.0..master | |
212 | ---------------- | |
2e0afafe | 213 | |
1d52b026 | 214 | You can use a basis based on time: |
ee8245b5 | 215 | |
8aa7eebf NS |
216 | ---------------- |
217 | $ git bundle create mybundle --since=10.days master | |
218 | ---------------- | |
2e0afafe | 219 | |
1d52b026 | 220 | You can use the number of commits: |
2e0afafe | 221 | |
8aa7eebf NS |
222 | ---------------- |
223 | $ git bundle create mybundle -10 master | |
224 | ---------------- | |
225 | ||
226 | You can run `git-bundle verify` to see if you can extract from a bundle | |
1d52b026 | 227 | that was created with a basis: |
8aa7eebf NS |
228 | |
229 | ---------------- | |
b1889c36 | 230 | $ git bundle verify mybundle |
8aa7eebf | 231 | ---------------- |
2e0afafe | 232 | |
8aa7eebf | 233 | This will list what commits you must have in order to extract from the |
1d52b026 | 234 | bundle and will error out if you do not have them. |
2e0afafe | 235 | |
8aa7eebf | 236 | A bundle from a recipient repository's point of view is just like a |
1d52b026 DM |
237 | regular repository which it fetches or pulls from. You can, for example, map |
238 | references when fetching: | |
2e0afafe | 239 | |
8aa7eebf NS |
240 | ---------------- |
241 | $ git fetch mybundle master:localRef | |
242 | ---------------- | |
2e0afafe | 243 | |
5e1f9605 | 244 | You can also see what references it offers: |
2e0afafe | 245 | |
8aa7eebf NS |
246 | ---------------- |
247 | $ git ls-remote mybundle | |
248 | ---------------- | |
2e0afafe | 249 | |
2e0afafe JS |
250 | GIT |
251 | --- | |
9e1f0a85 | 252 | Part of the linkgit:git[1] suite |