Submodule-modes.org

   1 Depending on the [[Submodule use cases][Submodule use case]] a different mode of operation
   2 should be chosen for a submodule. This table describes different
   3 update modes (/italics/ denote functionality that isn't implementeed
   4 in core git yet).
   5
   6 | Update mode | exact | branched |
   7 | Description | The SHA-1 recorded for the superproject is checked out as a detached HEAD | A local branch is used to integrate both local and upstream changes, still a SHA-1 is recorded to denote the exact submodule commit used |
   8 | Typical user | Developers who just consume the submodule as a black box, and don't develop it directly | Developers who actively develop the submodle |
   9 | Configuration | =submodule.<name>.update=: =checkout=, which is the default | =submodule.<name>.update=: set to =merge= or =rebase= depending on the desired update method, optionally =submodule.<name>.branch=: set to the upstream branch |
  10
  11 When you decide to update the SHA-1 recorded in the superproject, here are your choices:
  12
  13 | Update target | local | remote | custom |
  14 | Description | Update with the SHA-1 recorded in the superproject's tree | Update with the SHA-1 recorded in the remote subproject |
  15 | Example situation | After merging from the upstream subproject | After the subproject makes a release | You just felt like it ;) |
  16 | Invocation | =git submodule update= | =git submodule update --remote= | =cd submodule && git checkout …= |
  17
  18 Note that the update target just determines the /what/ should be
  19 integrated with the locally-checked-out submodule, and the update mode
  20 just determines /how/ a target should be integrated.  Feel free to mix
  21 and match.