]>
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] |
2e0afafe JS |
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 | ||
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 | |
26 | another repository using gitlink:git-fetch[1] and gitlink:git-pull[1] | |
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>:: | |
54 | Passes the objects in the bundle to gitlink: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 | gitlink:git-fetch[1]. | |
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 JS |
75 | necessarily everything in the pack (in this case, git-bundle is |
76 | acting like gitlink:git-fetch-pack[1]). | |
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. | |
102 | We set a tag in R1 (lastR2bundle) after the previous such transport, | |
103 | and move it afterwards to help build the bundle. | |
104 | ||
105 | in R1 on A: | |
106 | $ git-bundle create mybundle master ^lastR2bundle | |
107 | $ git tag -f lastR2bundle master | |
108 | ||
109 | (move mybundle from A to B by some mechanism) | |
110 | ||
111 | in R2 on B: | |
112 | $ git-bundle verify mybundle | |
113 | $ git-fetch mybundle refspec | |
114 | ||
115 | where refspec is refInBundle:localRef | |
116 | ||
117 | ||
118 | Also, with something like this in your config: | |
119 | ||
120 | [remote "bundle"] | |
121 | url = /home/me/tmp/file.bdl | |
122 | fetch = refs/heads/*:refs/remotes/origin/* | |
123 | ||
124 | You can first sneakernet the bundle file to ~/tmp/file.bdl and | |
125 | then these commands: | |
126 | ||
127 | $ git ls-remote bundle | |
128 | $ git fetch bundle | |
129 | $ git pull bundle | |
130 | ||
131 | would treat it as if it is talking with a remote side over the | |
132 | network. | |
133 | ||
134 | Author | |
135 | ------ | |
136 | Written by Mark Levedahl <mdl123@verizon.net> | |
137 | ||
138 | GIT | |
139 | --- | |
140 | Part of the gitlink:git[7] suite |