]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | Some libraries that Ceph uses are incorporated into the build tree |
2 | through a technique known as git subtrees. This is an alternative to | |
3 | git submodules, which is also used in Ceph. | |
4 | ||
5 | One such library is the dmclock library. Here are some basic notes on | |
6 | the use of git subtrees. | |
7 | ||
8 | When a subtree is added to the repo, commands such as these were run | |
9 | from the top-level ceph directory: | |
10 | ||
11 | git subtree add --prefix src/dmclock \ | |
12 | git@github.com:ceph/dmclock.git master --squash | |
13 | ||
14 | That essentially brings in a full copy of the library into the | |
15 | subdirectory src/dmclock, but squashes all the commits into a single | |
16 | one. | |
17 | ||
18 | If in time the library is updated and you'd like to bring the updates | |
19 | in, you could run: | |
20 | ||
21 | git subtree pull --prefix src/dmclock \ | |
22 | git@github.com:ceph/dmclock.git master --squash | |
23 | ||
24 | WARNINGS | |
25 | ||
26 | 1. A rebase should NEVER include the commits by which a subtree is | |
27 | added or pulled. Those commits do not include the prefix that was used | |
28 | for the subtree add/pull, and therefore the commits are applied to the | |
29 | wrong files or, more likely, to non-existant files. If something like | |
30 | this must be done, a workable approach is to a) do an interactive | |
31 | rebase, b) remove the commits for the former subtree add/pull, and | |
32 | either c) replace those commits with executions (x/exec) of the | |
33 | commands used to add/pull the subtrees, or d) do those commands from | |
34 | the command-line by using (e/edit) on preceding commits. | |
35 | ||
36 | 2. If you'd like to modify the library contained in a subtree you'll | |
37 | need to choose whether to just change your subtree and maintain those | |
38 | differences into the future (until the library incorporates them) or, | |
39 | if you're able, modify the library and use a "git subtree pull ..." to | |
40 | bring them in. | |
41 | ||
42 | 3. If you modify the library within the ceph tree, then it's best not | |
43 | to combine changes within the subtree and outside the subtree in a | |
44 | single commit. Each commit should either only contain changes within | |
45 | the subtree or outside the subtree. That gives you the option to | |
46 | cleanly push those changes back to the library's repo. That way if you | |
47 | ultimately decide to make the changes to the library, you can easily | |
48 | remove the subtree commits. |