diff options
Diffstat (limited to 'Documentation/gitsubmodules.txt')
| -rw-r--r-- | Documentation/gitsubmodules.txt | 34 |
1 files changed, 19 insertions, 15 deletions
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt index 0a89020..f7b5a25 100644 --- a/Documentation/gitsubmodules.txt +++ b/Documentation/gitsubmodules.txt @@ -3,7 +3,7 @@ gitsubmodules(7) NAME ---- -gitsubmodules - mounting one repository inside another +gitsubmodules - Mounting one repository inside another SYNOPSIS -------- @@ -78,7 +78,7 @@ Submodule operations can be configured using the following mechanisms * The command line for those commands that support taking submodules as part of their pathspecs. Most commands have a boolean flag - `--recurse-submodules` which specify whether to recurse into submodules. + `--recurse-submodules` which specifies whether to recurse into submodules. Examples are `grep` and `checkout`. Some commands take enums, such as `fetch` and `push`, where you can specify how submodules are affected. @@ -151,7 +151,7 @@ the superproject's `$GIT_DIR/config` file, so the superproject's history is not affected. This can be undone using `git submodule init`. * Deleted submodule: A submodule can be deleted by running -`git rm <submodule path> && git commit`. This can be undone +`git rm <submodule-path> && git commit`. This can be undone using `git revert`. + The deletion removes the superproject's tracking data, which are @@ -192,7 +192,7 @@ For example: [submodule "baz"] url = https://example.org/baz -In the above config only the submodule 'bar' and 'baz' are active, +In the above config only the submodules 'bar' and 'baz' are active, 'bar' due to (1) and 'baz' due to (3). 'foo' is inactive because (1) takes precedence over (3) @@ -225,11 +225,11 @@ presence of the .url field. Workflow for a third party library ---------------------------------- - # add a submodule - git submodule add <url> <path> + # Add a submodule + git submodule add <URL> <path> - # occasionally update the submodule to a new version: - git -C <path> checkout <new version> + # Occasionally update the submodule to a new version: + git -C <path> checkout <new-version> git add <path> git commit -m "update submodule to new version" @@ -246,20 +246,23 @@ Workflow for an artificially split repo # regular commands recurse into submodules by default git config --global submodule.recurse true - # Unlike the other commands below clone still needs + # Unlike most other commands below, clone still needs # its own recurse flag: git clone --recurse <URL> <directory> cd <directory> # Get to know the code: git grep foo - git ls-files + git ls-files --recurse-submodules + +[NOTE] +`git ls-files` also requires its own `--recurse-submodules` flag. # Get new code git fetch git pull --rebase - # change worktree + # Change worktree git checkout git reset @@ -267,11 +270,12 @@ Implementation details ---------------------- When cloning or pulling a repository containing submodules the submodules -will not be checked out by default; You can instruct 'clone' to recurse -into submodules. The 'init' and 'update' subcommands of 'git submodule' +will not be checked out by default; you can instruct `clone` to recurse +into submodules. The `init` and `update` subcommands of `git submodule` will maintain submodules checked out and at an appropriate revision in -your working tree. Alternatively you can set 'submodule.recurse' to have -'checkout' recursing into submodules. +your working tree. Alternatively you can set `submodule.recurse` to have +`checkout` recurse into submodules (note that `submodule.recurse` also +affects other Git commands, see linkgit:git-config[1] for a complete list). SEE ALSO |