Submodule-modes: Distinguish between update modes and update targets

diff --git a/Submodule-modes.org b/Submodule-modes.org
index 05d5c0d476f220d78fe9491461992c10806bd2f6..22d19875df8bc241863b6fff3405e05e170cdaeb 100644 (file)
--- a/Submodule-modes.org
+++ b/Submodule-modes.org
@@ -1,6 +1,21 @@
-Depending on the [[Submodule use cases][Submodule use case]] a different mode of operation should be chosen for a submodule. This table describes different modes (/italics/ denote functionality that isn't implementeed in core git yet).
+Depending on the [[Submodule use cases][Submodule use case]] a different mode of operation
+should be chosen for a submodule. This table describes different
+update modes (/italics/ denote functionality that isn't implementeed
+in core git yet).

 
 

-| Submodule mode | exact | branch | floating |
-| 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 | A local branch follows a remote branch, the SHA-1 only serves as an initial starting point and may be updated to record releases or other special occasions, but doesn't have to |
-| Typical use case | Content shared between different repos | Content shared between different repos | Content managed by somebody else |
-| Configuration | =submodule.<name>.update=: =checkout=, which is the default | =submodule.<name>.update=: set to =merge= or =rebase= depending on the desired update method | =submodule.<name>.branch=: set to the upstream branch |
\ No newline at end of file
+| Update mode | exact | branched |
+| 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 |
+| Typical user | Developers who just consume the submodule as a black box, and don't develop it directly | Developers who actively develop the submodle |
+| 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 |
+
+When you decide to update the SHA-1 recorded in the superproject, here are your choices:
+
+| Update target | local | remote | custom |
+| Description | Update with the SHA-1 recorded in the superproject's tree | Update with the SHA-1 recorded in the remote subproject |
+| Example situation | After merging from the upstream subproject | After the subproject makes a release | You just felt like it ;) |
+| Invocation | =git submodule update= | =git submodule update --remote= | =cd submodule && git checkout …= |
+
+Note that the update target just determines the /what/ should be
+integrated with the locally-checked-out submodule, and the update mode
+just determines /how/ a target should be integrated.  Feel free to mix
+and match.