src/ceph/README.git-subtree

   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.