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