]>
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 | |
22 | be directly connected so the interactive git protocols (git, ssh, | |
20f50f16 | 23 | rsync, http) cannot be used. This command provides support for |
2e0afafe JS |
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 | |
5162e697 | 26 | another repository using linkgit:git-fetch[1] and linkgit:git-pull[1] |
2e0afafe JS |
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>:: | |
5162e697 | 54 | Passes the objects in the bundle to linkgit:git-index-pack[1] |
2e0afafe JS |
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 | |
5162e697 | 59 | linkgit:git-fetch[1]. |
2e0afafe JS |
60 | |
61 | [git-rev-list-args...]:: | |
20f50f16 | 62 | A list of arguments, acceptable to git-rev-parse and |
2e0afafe JS |
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 | |
20f50f16 | 74 | expects to receive only those references asked for and not |
2e0afafe | 75 | necessarily everything in the pack (in this case, git-bundle is |
5162e697 | 76 | acting like linkgit:git-fetch-pack[1]). |
2e0afafe JS |
77 | |
78 | SPECIFYING REFERENCES | |
79 | --------------------- | |
80 | ||
81 | git-bundle will only package references that are shown by | |
82 | git-show-ref: this includes heads, tags, and remote heads. References | |
83 | such as master~1 cannot be packaged, but are perfectly suitable for | |
84 | defining the basis. More than one reference may be packaged, and more | |
85 | than one basis can be specified. The objects packaged are those not | |
86 | contained in the union of the given bases. Each basis can be | |
87 | specified explicitly (e.g., ^master~10), or implicitly (e.g., | |
88 | master~10..master, master --since=10.days.ago). | |
89 | ||
90 | It is very important that the basis used be held by the destination. | |
20f50f16 | 91 | It is okay to err on the side of conservatism, causing the bundle file |
2e0afafe JS |
92 | to contain objects already in the destination as these are ignored |
93 | when unpacking at the destination. | |
94 | ||
95 | EXAMPLE | |
96 | ------- | |
97 | ||
98 | Assume two repositories exist as R1 on machine A, and R2 on machine B. | |
99 | For whatever reason, direct connection between A and B is not allowed, | |
100 | but we can move data from A to B via some mechanism (CD, email, etc). | |
101 | We want to update R2 with developments made on branch master in R1. | |
99d8ea2c SB |
102 | |
103 | To create the bundle you have to specify the basis. You have some options: | |
104 | ||
105 | - Without basis. | |
106 | + | |
107 | This is useful when sending the whole history. | |
108 | ||
109 | ------------ | |
110 | $ git bundle create mybundle master | |
111 | ------------ | |
112 | ||
113 | - Using temporally tags. | |
114 | + | |
2e0afafe JS |
115 | We set a tag in R1 (lastR2bundle) after the previous such transport, |
116 | and move it afterwards to help build the bundle. | |
117 | ||
ee8245b5 | 118 | ------------ |
b1889c36 | 119 | $ git bundle create mybundle master ^lastR2bundle |
2e0afafe | 120 | $ git tag -f lastR2bundle master |
ee8245b5 | 121 | ------------ |
2e0afafe | 122 | |
99d8ea2c SB |
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 | ------------ | |
2e0afafe | 134 | |
99d8ea2c | 135 | - With a limit on the number of commits |
ee8245b5 MV |
136 | |
137 | ------------ | |
99d8ea2c | 138 | $ git bundle create mybundle master -n 10 |
ee8245b5 | 139 | ------------ |
2e0afafe | 140 | |
99d8ea2c | 141 | Then you move mybundle from A to B, and in R2 on B: |
2e0afafe | 142 | |
99d8ea2c | 143 | ------------ |
b1889c36 JN |
144 | $ git bundle verify mybundle |
145 | $ git fetch mybundle master:localRef | |
99d8ea2c | 146 | ------------ |
2e0afafe | 147 | |
99d8ea2c | 148 | With something like this in the config in R2: |
2e0afafe | 149 | |
99d8ea2c | 150 | ------------------------ |
2e0afafe JS |
151 | [remote "bundle"] |
152 | url = /home/me/tmp/file.bdl | |
153 | fetch = refs/heads/*:refs/remotes/origin/* | |
99d8ea2c | 154 | ------------------------ |
2e0afafe JS |
155 | |
156 | You can first sneakernet the bundle file to ~/tmp/file.bdl and | |
99d8ea2c | 157 | then these commands on machine B: |
2e0afafe | 158 | |
ee8245b5 | 159 | ------------ |
2e0afafe JS |
160 | $ git ls-remote bundle |
161 | $ git fetch bundle | |
162 | $ git pull bundle | |
ee8245b5 | 163 | ------------ |
2e0afafe JS |
164 | |
165 | would treat it as if it is talking with a remote side over the | |
166 | network. | |
167 | ||
168 | Author | |
169 | ------ | |
170 | Written by Mark Levedahl <mdl123@verizon.net> | |
171 | ||
172 | GIT | |
173 | --- | |
9e1f0a85 | 174 | Part of the linkgit:git[1] suite |