From: W. Trevor King Date: Thu, 9 Jan 2014 22:38:06 +0000 (-0800) Subject: Submodule-modes: Distinguish between update modes and update targets X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;ds=inline;p=git-submod-enhancements.wiki.git Submodule-modes: Distinguish between update modes and update targets --- diff --git a/Submodule-modes.org b/Submodule-modes.org index 05d5c0d..22d1987 100644 --- 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..update=: =checkout=, which is the default | =submodule..update=: set to =merge= or =rebase= depending on the desired update method | =submodule..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..update=: =checkout=, which is the default | =submodule..update=: set to =merge= or =rebase= depending on the desired update method, optionally =submodule..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.