IMP logo
IMP Manual  for IMP version 2.6.1
subtree.md
1 git submodules and subtrees {#subtree}
2 ===========================
3 
4 %IMP includes several pieces of code that are actually maintained in
5 separate git repositories on [GitHub](https://github.com). These include
6 the [RMF library](https://github.com/salilab/rmf) and the
7 [IMP::pmi module](https://github.com/salilab/pmi). There are two main ways
8 to achieve this with git: `git submodule` and `git subtree`. Modern versions
9 of %IMP use `git subtree` (we previously used `submodule`; see the
10 [issue on GitHub](https://github.com/salilab/imp/issues/876) for a discussion).
11 `subtree` is a little harder for developers to work with than `submodule`,
12 but is much easier for end users (no need to run any setup scripts after
13 getting %IMP, forks of the %IMP repository work, and GitHub's "Download ZIP"
14 feature works).
15 
16 [This blog post](http://blogs.atlassian.com/2013/05/alternatives-to-git-submodule-git-subtree/)
17 covers several useful commands for working with `git subtree`.
18 
19 As an %example, a typical workflow for working with the IMP::pmi module is:
20 
21  - `git clone` %IMP as per usual
22  - Work on the PMI module in `modules/pmi`
23  - Use regular `git` commands `git add`, `git commit` etc. to record changes
24  - Periodically push them to the PMI repository (_not_ the main %IMP repository) by running (in the top level %IMP directory)
25 
26  `git subtree push --prefix=modules/pmi git@github.com:salilab/pmi.git develop`
27 
28  - *Important*: be careful not to also push these commits to %IMP. You
29  may need to use `git reset HEAD~N` (where `N` is the number of commits
30  you made) to remove them from %IMP (or, if you made both PMI commits
31  and regular %IMP commits, use `git rebase -i` to delete just the PMI
32  commits). Use `git subtree pull` (below) to incorporate PMI changes
33  into %IMP.
34  - `git subtree push` is very slow, since it has to examine every commit
35  in the %IMP repository.
36  - If this fails with `fatal: bad object`, then it needs you to do a
37  `tools/git/update-pmi.sh` or `git subtree pull` (see below) first.
38 
39  - To incorporate changes from the PMI repository into %IMP, use the utility
40  script
41 
42  `tools/git/update-pmi.sh`
43 
44  - This will squash all of the PMI changes into a single %IMP
45  commit, which you can then `git push` into the %IMP repository in the
46  normal way. (There is a `git subtree pull` command which is supposed to
47  achieve the same thing, but the syntax is more complicated, and we find
48  that often the commits it generates are enormous and touch
49  every file in %IMP.)
50 
51 Note that since `git subtree` commands can be very slow, if you will be working
52 a lot with a subtree it is probably faster to checkout its own repository
53 directly and then use regular `git push` and `git pull` to work inside it.
54 (For example, you could checkout the PMI repository into `~/pmi`, then
55 temporarily replace the subtree in %IMP with a symlink to the real repository
56 with something like `cd ~/imp/imp/modules; mv pmi pmi.old; ln -sf ~/pmi pmi`.
57 Move back `pmi.old` when you're done, then use `update-pmi.sh` to incorporate
58 the PMI changes into %IMP.)