Flexible, Enhanced Submodule Management for Git
Git-fleximod is a Python-based tool that extends Git's submodule and sparse checkout capabilities, offering additional features for managing submodules in a more flexible and efficient way.
If you choose to locate git-fleximod in your path you can access it via command: git fleximod
Basic Usage:
git fleximod <command> [options]
Available Commands:
status: Display the status of submodules.
update: Update submodules to the tag indicated in .gitmodules variable fxtag.
test: Make sure that fxtags and submodule hashes are consistant,
make sure that official urls (as defined by fxDONOTUSEurl) are set
make sure that fxtags are defined for all submodules
Additional Options:
See git fleximod --help for more details.
fxtag: Specify a specific tag or branch to checkout for a submodule.
fxrequired: Mark a submodule's checkout behavior, with allowed values:
- ToplevelRequired: Top-level and required (checked out only when this is the Toplevel module).
- ToplevelOptional: Top-level and optional (checked out with --optional flag if this is the Toplevel module).
- AlwaysRequired: Always required (always checked out).
- AlwaysOptional: Always optional (checked out with --optional flag).
fxsparse: Enable sparse checkout for a submodule, pointing to a file containing sparse checkout paths.
fxDONOTUSEurl: This is the url used in the test subcommand to assure that protected branches do not point to forks
**NOTE** the fxDONOTUSEurl variable is only used to identify the official project repository and should not be
changed by users. Use the url variable to change to a fork if desired.
To enable sparse checkout for a submodule, set the fxsparse variable
in the .gitmodules file to the path of a file containing the desired
sparse checkout paths. Git-fleximod will automatically configure
sparse checkout based on this file when applicable commands are run.
See [git-sparse-checkout](https://git-scm.com/docs/git-sparse-checkout#_internalsfull_pattern_set)
for details on the format of this file.
The git fleximod test action is designed to be used by, for example, github workflows to assure that protected branches are consistant with respect to submodule hashes and fleximod fxtags
Here are some common usage examples:
Update all submodules, including optional ones:
git fleximod update --optionalUpdating a specific submodule to the fxtag indicated in .gitmodules:
git fleximod update submodule-nameExample .gitmodules entry:
[submodule "cosp2"]
path = src/physics/cosp2/src
url = https://github.com/CFMIP/COSPv2.0
fxsparse = ../.cosp_sparse_checkout
fxrequired = AlwaysRequired
fxtag = v2.1.4cesmExplanation:
This entry indicates that the submodule named cosp2 at tag v2.1.4cesm should be checked out into the directory src/physics/cosp2/src relative to the .gitmodules directory. It should be checked out from the URL https://github.com/CFMIP/COSPv2.0 and use sparse checkout as described in the file ../.cosp_sparse_checkout relative to the path directory. It should be checked out anytime this .gitmodules entry is read.
Additional example:
[submodule "cime"]
path = cime
url = https://github.com/jedwards4b/cime
fxrequired = ToplevelRequired
fxtag = cime6.0.198_rme01Explanation:
This entry indicates that the submodule cime should be checked out into a directory named cime at tag cime6.0.198_rme01 from the URL https://github.com/jedwards4b/cime. This should only be done if the .gitmodules file is at the top level of the repository clone.
We welcome contributions! Please see the CONTRIBUTING.md file for guidelines.
Git-fleximod is released under the MIT License.