IMP logo
IMP Manual  for IMP version 2.16.0
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`. However,
18 `git subtree` commands are hard to use correctly can be very slow, so it's
19 generally easier to use this procedure when working on PMI:
20 
21  - Build %IMP as per usual, say in `~/imp/build/`.
22  - Don't touch the files in `~/imp/modules/pmi`; instead `git clone` the PMI
23  repository into a new directory, separate from %IMP, say `~/pmi/`.
24  - Make a new directory for the PMI build, e.g. `~/pmi/build`, then
25  do an *out-of-tree* build of PMI with:
26 
27  `cmake .. -G Ninja -DIMP_DIR=~/imp/build/ && ninja`
28 
29  - Use regular `git` commands `git add`, `git commit`, `git push` etc. to
30  record changes to the PMI repository. Test changes using `ctest` or
31  the `setup_environment.sh` script in `~/pmi/build`.
32  - To incorporate changes from the PMI repository into %IMP, first push them
33  to the PMI repository, then use the utility script (in the IMP clone)
34 
35  `tools/git/update-pmi.sh`
36 
37  - This will squash all of the PMI changes into a single %IMP
38  commit, which can then be `git push`ed into the %IMP repository in the
39  normal way.