summaryrefslogtreecommitdiff
path: root/Documentation/git-submodule.txt
AgeCommit message (Collapse)AuthorFilesLines
2020-02-14Merge branch 'km/submodule-doc-use-sm-path' into maintLibravatar Junio C Hamano1-1/+1
Docfix. * km/submodule-doc-use-sm-path: submodule foreach: replace $path with $sm_path in example
2020-01-31submodule foreach: replace $path with $sm_path in exampleLibravatar Kyle Meyer1-1/+1
f0fd0dc5c5 (submodule foreach: document '$sm_path' instead of '$path', 2018-05-08) updated the documentation to advise callers to favor $sm_path over the deprecated synonym $path. However, the example in that section still uses $path. Update it to use $sm_path. Signed-off-by: Kyle Meyer <kyle@kyleam.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-08Merge branch 'tm/doc-submodule-absorb-fix'Libravatar Junio C Hamano1-1/+1
Typofix. * tm/doc-submodule-absorb-fix: doc: submodule: fix typo for command absorbgitdirs
2020-01-06doc: submodule: fix typo for command absorbgitdirsLibravatar Thomas Menzel1-1/+1
The sentence wants to talk about the superproject's possesive, not plural form. Signed-off-by: Thomas Menzel <dev@tomsit.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-12-10Merge branch 'dl/submodule-set-url'Libravatar Junio C Hamano1-0/+6
"git submodule" learned a subcommand "set-url". * dl/submodule-set-url: submodule: teach set-url subcommand
2019-12-05Merge branch 'mg/doc-submodule-status-cached'Libravatar Junio C Hamano1-0/+3
"git submodule status" and "git submodule status --cached" show different things, but the documentation did not cover them correctly, which has been corrected. * mg/doc-submodule-status-cached: doc: document 'git submodule status --cached'
2019-12-05Merge branch 'pb/submodule-update-fetches'Libravatar Junio C Hamano1-1/+2
Doc update. * pb/submodule-update-fetches: doc: mention that 'git submodule update' fetches missing commits
2019-11-24doc: mention that 'git submodule update' fetches missing commitsLibravatar Philippe Blain1-1/+2
'git submodule update' will fetch new commits from the submodule remote if the SHA-1 recorded in the superproject is not found. This was not mentioned in the documentation. Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-24doc: document 'git submodule status --cached'Libravatar Manish Goregaokar1-0/+3
'git submodule status --cached' reports the SHAs recorded in the index of the superproject, instead of the SHAs that are checked out in the submodule. Signed-off-by: Manish Goregaokar <manishsmail@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-10-30submodule: teach set-url subcommandLibravatar Denton Liu1-0/+6
Currently, in the event that a submodule's upstream URL changes, users have to manually alter the URL in the .gitmodules file then run `git submodule sync`. Let's make that process easier. Teach submodule the set-url subcommand which will automatically change the `submodule.$name.url` property in the .gitmodules file and then run `git submodule sync` to complete the process. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-10-07Merge branch 'dl/submodule-set-branch'Libravatar Junio C Hamano1-1/+2
Docfix. * dl/submodule-set-branch: git-submodule.txt: fix AsciiDoc formatting error
2019-09-16git-submodule.txt: fix AsciiDoc formatting errorLibravatar Denton Liu1-1/+2
In b57e8119e6 (submodule: teach set-branch subcommand, 2019-02-08), the `set-branch` subcommand was added for submodules. When the documentation was written, the syntax for a "index term" in AsciiDoc was accidentally used. This caused the documentation to be rendered as set-branch -d|--default)|(-b|--branch <branch> [--] <path> instead of set-branch ((-d|--default)|(-b|--branch <branch>)) [--] <path> In addition to this, the original documentation was possibly confusing as it made it seem as if the `-b` option didn't accept a `<branch>` argument. Break `--default` and `--branch` into their own separate invocations to make it obvious that these options are mutually exclusive. Also, this removes the surrounding parentheses so that the "index term" syntax is not triggered. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-04-25Merge branch 'dl/submodule-set-branch'Libravatar Junio C Hamano1-3/+11
"git submodule" learns "set-branch" subcommand that allows the submodule.*.branch settings to be modified. * dl/submodule-set-branch: submodule: teach set-branch subcommand submodule--helper: teach config subcommand --unset git-submodule.txt: "--branch <branch>" option defaults to 'master'
2019-04-22Merge branch 'cb/doco-mono'Libravatar Junio C Hamano1-1/+1
Clean-up markup in the documentation suite. * cb/doco-mono: doc: format pathnames and URLs as monospace. doc/CodingGuidelines: URLs and paths as monospace
2019-04-10submodule: teach set-branch subcommandLibravatar Denton Liu1-0/+7
This teaches git-submodule the set-branch subcommand which allows the branch of a submodule to be set through a porcelain command without having to manually manipulate the .gitmodules file. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-03-13doc: format pathnames and URLs as monospace.Libravatar Corentin BOMPARD1-1/+1
Applying CodingGuidelines about monospace on pathnames and URLs. See Documentation/CodingGuidelines.txt for more information. Signed-off-by: Corentin BOMPARD <corentin.bompard@etu.univ-lyon1.fr> Signed-off-by: Nathan BERBEZIER <nathan.berbezier@etu.univ-lyon1.fr> Signed-off-by: Pablo CHABANNE <pablo.chabanne@etu.univ-lyon1.fr> Signed-off-by: Matthieu MOY <matthieu.moy@univ-lyon1.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-02-15submodule: document default behaviorLibravatar Denton Liu1-0/+4
submodule's default behavior wasn't documented in both git-submodule.txt and in the usage text of git-submodule. Document the default behavior similar to how git-remote does it. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-02-07git-submodule.txt: "--branch <branch>" option defaults to 'master'Libravatar Denton Liu1-3/+4
This behavior is mentioned in gitmodules.txt but not in git-submodule.txt so we copy the information over so that it is not missed. Also, add the missed argument to the -b/--branch option. Signed-off-by: Denton Liu <liu.denton@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-06-25Merge branch 'pc/submodule-helper-foreach'Libravatar Junio C Hamano1-5/+10
The bulk of "git submodule foreach" has been rewritten in C. * pc/submodule-helper-foreach: submodule: port submodule subcommand 'foreach' from shell to C submodule foreach: document variable '$displaypath' submodule foreach: document '$sm_path' instead of '$path' submodule foreach: correct '$path' in nested submodules from a subdirectory
2018-06-18Merge branch 'rd/doc-remote-tracking-with-hyphen'Libravatar Junio C Hamano1-2/+2
Doc update. * rd/doc-remote-tracking-with-hyphen: Use hyphenated "remote-tracking branch" (docs and comments)
2018-06-13Use hyphenated "remote-tracking branch" (docs and comments)Libravatar Robert P. J. Day1-2/+2
Use the obvious consensus of hyphenated "remote-tracking branch", and fix an obvious typo, all in documentation and comments. Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-30Merge branch 'cf/submodule-progress-dissociate'Libravatar Junio C Hamano1-1/+16
"git submodule update" and "git submodule add" supported the "--reference" option to borrow objects from a neighbouring local repository like "git clone" does, but lacked the more recent invention "--dissociate". Also "git submodule add" has been taught to take the "--progress" option. * cf/submodule-progress-dissociate: submodule: add --dissociate option to add/update commands submodule: add --progress option to add command submodule: clean up substitutions in script
2018-05-22submodule: add --dissociate option to add/update commandsLibravatar Casey Fitzpatrick1-1/+9
Add --dissociate option to add and update commands, both clone helper commands that already have the --reference option --dissociate pairs with. Signed-off-by: Casey Fitzpatrick <kcghost@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-22submodule: add --progress option to add commandLibravatar Casey Fitzpatrick1-0/+7
The '--progress' was introduced in 72c5f88311d (clone: pass --progress decision to recursive submodules, 2016-09-22) to fix the progress reporting of the clone command. Also add the progress option to the 'submodule add' command. The update command already supports the progress flag, but it is not documented. Signed-off-by: Casey Fitzpatrick <kcghost@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-09submodule foreach: document variable '$displaypath'Libravatar Prathamesh Chavan1-3/+5
It was observed that the variable '$displaypath' was accessible but undocumented. Hence, document it. Discussed-with: Ramsay Jones <ramsay@ramsayjones.plus.com> Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Prathamesh Chavan <pc44800@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-05-09submodule foreach: document '$sm_path' instead of '$path'Libravatar Prathamesh Chavan1-4/+7
As using a variable '$path' may be harmful to users due to capitalization issues, see 64394e3ae9 (git-submodule.sh: Don't use $path variable in eval_gettext string, 2012-04-17). Adjust the documentation to advocate for using $sm_path, which contains the same value. We still make the 'path' variable available and document it as a deprecated synonym of 'sm_path'. Discussed-with: Ramsay Jones <ramsay@ramsayjones.plus.com> Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Prathamesh Chavan <pc44800@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2018-04-18git-submodule.txt: quote usage in monospace, drop backslashLibravatar Martin Ågren1-2/+2
We tend to quote command line examples using `` to set them in a monospace font. The immediate motivation for this patch is to get rid of another instance of \--. As noted in the previous commits, \-- has a tendency of rendering badly. Here, it renders ok (at least with AsciiDoc 8.6.9 and Asciidoctor 1.5.4), but by getting rid of this instance, we reduce the chances of \-- cropping up in places where it matters more. Signed-off-by: Martin Ågren <martin.agren@gmail.com>
2018-01-16Doc/git-submodule: improve readability and grammar of a sentenceLibravatar Kaartic Sivaraam1-8/+8
While at it, correctly quote important words. Signed-off-by: Kaartic Sivaraam <kaartic.sivaraam@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-07-12Merge branch 'sb/submodule-doc'Libravatar Junio C Hamano1-34/+10
Doc update. * sb/submodule-doc: submodules: overhaul documentation
2017-06-30Merge branch 'vs/typofixes'Libravatar Junio C Hamano1-1/+1
Many typofixes. * vs/typofixes: Spelling fixes
2017-06-27Spelling fixesLibravatar Ville Skyttä1-1/+1
Signed-off-by: Ville Skyttä <ville.skytta@iki.fi> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-06-22submodules: overhaul documentationLibravatar Stefan Beller1-34/+10
This patch aims to detangle (a) the usage of `git-submodule` from (b) the concept of submodules and (c) how the actual implementation looks like, such as where they are configured and (d) what the best practices are. To do so, move the conceptual parts of the 'git-submodule' man page to a new man page gitsubmodules(7). This new page is just like gitmodules(5), gitattributes(5), gitcredentials(7), gitnamespaces(7), gittutorial(7), which introduce a concept rather than explaining a specific command. Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-06-22Documentation/git-submodule: cleanup "add" sectionLibravatar Kaartic Sivaraam1-28/+21
The "add" section for 'git-submodule' is redundant in its description and the short synopsis line. Fix it. Remove the redundant mentioning of the 'repository' argument being mandatory. The text is hard to read because of back-references, so remove those. Replace the word "humanish" by "canonical" as that conveys better what we do to guess the path. While at it, quote all occurrences of '.gitmodules' as that is an important file in the submodule context, also link to it on its first mention. Helped-by: Stefan Beller <sbeller@google.com> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> Reviewed-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-03-18submodule init: initialize active submodulesLibravatar Brandon Williams1-1/+3
Teach `submodule init` to initialize submodules which have been configured to be active by setting 'submodule.active' with a pathspec. Now if no path arguments are given and 'submodule.active' is configured, `init` will initialize all submodules which have been configured to be active. If no path arguments are given and 'submodule.active' is not configured, then `init` will retain the old behavior of initializing all submodules. This allows users to record more complex patterns as it saves retyping them whenever you invoke update. Signed-off-by: Brandon Williams <bmwill@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-02-28submodule init: warn about falling back to a local pathLibravatar Stefan Beller1-14/+24
When a submodule is initialized, the config variable 'submodule.<name>.url' is set depending on the value of the same variable in the .gitmodules file. When the URL indicates to be relative, then the url is computed relative to its default remote. The default remote cannot be determined accurately in all cases, such that it falls back to 'origin'. The 'origin' remote may not exist, though. In that case we give up looking for a suitable remote and we'll just assume it to be a local relative path. This can be confusing to users as there is a lot of guessing involved, which is not obvious to the user. So in the corner case of assuming a local autoritative truth, warn the user to lessen the confusion. This behavior was introduced in 4d6893200 (submodule add: allow relative repository path even when no url is set, 2011-06-06), which shared the code with submodule-init and then ported to C in 3604242f080a (submodule: port init from shell to C, 2016-04-15). In case of submodule-add, this behavior makes sense in some use cases[1], however for submodule-init there does not seem to be an immediate obvious use case to fall back to a local submodule. However there might be, so warn instead of die here. While adding the warning, also clarify the behavior of relative URLs in the documentation. [1] e.g. http://stackoverflow.com/questions/8721984/git-ignore-files-for-public-repository-but-not-for-private "store a secret locally in a submodule, with no intention to publish it" Reported-by: Shawn Pearce <spearce@spearce.org> Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-02-15Merge branch 'jk/doc-submodule-markup-fix'Libravatar Junio C Hamano1-3/+6
Doc markup fix. * jk/doc-submodule-markup-fix: docs/git-submodule: fix unbalanced quote
2017-02-13docs/git-submodule: fix unbalanced quoteLibravatar Jeff King1-3/+6
The documentation gives an example of the submodule foreach command that uses both backticks and single-quotes. We stick the whole thing inside "+" markers to make it monospace, but the inside punctuation still needs escaping. We handle the backticks with "{backtick}", and use backslash-escaping for the single-quotes. But we missed the escaping on the second quote. Fortunately, asciidoc renders this unbalanced quote as we want (showing the quote), but asciidoctor does not. We could fix it by adding the missing backslash. However, let's take a step back. Even when rendered correctly, it's hard to read a long command stuck into the middle of a paragraph, and the important punctuation is hard to notice. Let's instead bump it into its own single-line code block. That makes both the source and the rendered result more readable, and as a bonus we don't have to worry about quoting at all. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-01-12submodule update documentation: don't repeat ourselvesLibravatar Stefan Beller1-16/+14
The documentation for the `git submodule update` command, repeats itself for each update option, "This is done when <option> is given, or no option is given and `submodule.<name>.update` is set to <string>. Avoid these repetitive clauses by stating the command line options take precedence over configured options. Also add 'none' to the list of options instead of mentioning it in the following running text and split the list into two parts, one that is accessible via the command line and one that is only reachable via the configuration variables. Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-01-12submodule documentation: add options to the subcommandLibravatar Stefan Beller1-16/+11
When reading up on a subcommand of `git submodule <subcommand>`, it is convenient to have its options nearby and not just at the top of the man page. Add the options to each subcommand. While at it, also document the `--checkout` option for `update`. Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-12-12submodule: add absorb-git-dir functionLibravatar Stefan Beller1-0/+15
When a submodule has its git dir inside the working dir, the submodule support for checkout that we plan to add in a later patch will fail. Add functionality to migrate the git directory to be absorbed into the superprojects git directory. The newly added code in this patch is structured such that other areas of Git can also make use of it. The code in the submodule--helper is a mere wrapper and option parser for the function `absorb_git_dir_into_superproject`, that takes care of embedding the submodules git directory into the superprojects git dir. That function makes use of the more abstract function for this use case `relocate_gitdir`, which can be used by e.g. the worktree code eventually to move around a git directory. Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-10-19submodules doc: update documentation for "." used for submodule branchesLibravatar Brandon Williams1-1/+3
4d7bc52b17 ("submodule update: allow '.' for branch value", 2016-08-03) adopted from Gerrit a feature to set "." as a special value of "submodule.<name>.branch" in .gitmodules file to indicate that the tracking branch in the submodule should be the same as the current branch in the superproject. Update the documentation to describe this. Signed-off-by: Brandon Williams <bmwill@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-05-27submodule update: learn `--[no-]recommend-shallow` optionLibravatar Stefan Beller1-2/+9
Sometimes the history of a submodule is not considered important by the projects upstream. To make it easier for downstream users, allow a boolean field 'submodule.<name>.shallow' in .gitmodules, which can be used to recommend whether upstream considers the history important. This field is honored in the initial clone by default, it can be ignored by giving the `--no-recommend-shallow` option. Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-05-17Merge branch 'sb/submodule-deinit-all'Libravatar Junio C Hamano1-6/+13
Correct faulty recommendation to use "git submodule deinit ." when de-initialising all submodules, which would result in a strange error message in a pathological corner case. * sb/submodule-deinit-all: submodule deinit: require '--all' instead of '.' for all submodules
2016-05-05submodule deinit: require '--all' instead of '.' for all submodulesLibravatar Stefan Beller1-6/+13
The discussion in [1] pointed out that '.' is a faulty suggestion as there is a corner case where it fails: > "submodule deinit ." may have "worked" in the sense that you would > have at least one path in your tree and avoided this "nothing > matches" most of the time. It would have still failed with the > exactly same error if run in an empty repository, i.e. > > $ E=/var/tmp/x/empty && rm -fr "$E" && mkdir -p "$E" && cd "$E" > $ git init > $ rungit v2.6.6 submodule deinit . > error: pathspec '.' did not match any file(s) known to git. > Did you forget to 'git add'? > $ >file && git add file > $ rungit v2.6.6 submodule deinit . > $ echo $? > 0 So instead of a pathspec add the '--all' option to deinit all submodules and add a test to check for the corner case of an empty repository. The code only needs to learn about the '--all' option and doesn't require further changes as `git submodule--helper list "$@"` will list all submodules when "$@" is empty. [1] http://news.gmane.org/gmane.comp.version-control.git/289535 Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Stefan Beller <sbeller@google.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-03-01submodule update: expose parallelism to the userLibravatar Stefan Beller1-1/+6
Expose possible parallelism either via the "--jobs" CLI parameter or the "submodule.fetchJobs" setting. By having the variable initialized to -1, we make sure 0 can be passed into the parallel processing machine, which will then pick as many parallel workers as there are CPUs. Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-12-04document submodule sync --recursiveLibravatar Stefan Beller1-1/+4
The git-submodule(1) is inconsistent. In the synopsis, it says: git submodule [--quiet] sync [--recursive] [--] [<path>...] The description of the sync does not mention --recursive, and the description of --recursive says that it is only available for foreach, update and status. The option was introduced (82f49f294c, Teach --recursive to submodule sync, 2012-10-26) a while ago, so let's document it, too. Reported-by: Per Cederqvist <cederp@opera.com> Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-05-28submodule doc: reorder introductory paragraphsLibravatar Stefan Beller1-28/+22
It's better to start the man page with a description of what submodules actually are, instead of saying what they are not. Reorder the paragraphs such that - the first short paragraph introduces the submodule concept, - the second paragraph highlights the usage of the submodule command, - the third paragraph giving background information, and finally - the fourth paragraph discusing alternatives such as subtrees and remotes, which we don't want to be confused with. This ordering deepens the knowledge on submodules with each paragraph. First the basic questions like "How/what" will be answered, while the underlying concepts will be taught at a later time. Making sure it is not confused with subtrees and remotes is not really enhancing knowledge of submodules itself, but rather painting the big picture of git concepts, so you could also argue to have it as the second paragraph. Personally I think this may confuse readers, specially newcomers though. Additionally to reordering the paragraphs, they have been slightly reworded. Signed-off-by: Stefan Beller <sbeller@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2015-03-02submodule: improve documentation of update subcommandLibravatar Michal Sojka1-20/+46
The documentation of 'git submodule update' has several problems: 1) It mentions that value 'none' of submodule.$name.update can be overridden by --checkout, but other combinations of configuration values and command line options are not mentioned. 2) The documentation of submodule.$name.update is scattered across three places, which is confusing. 3) The documentation of submodule.$name.update in gitmodules.txt is incorrect, because the code always uses the value from .git/config and never from .gitmodules. 4) Documentation of --force was incomplete, because it is only effective in case of checkout method of update. Fix all these problems by documenting submodule.*.update in git-submodule.txt and make everybody else refer to it. Helped-by: Junio C Hamano <gitster@pobox.com> Helped-by: Jens Lehmann <Jens.Lehmann@web.de> Signed-off-by: Michal Sojka <sojkam1@fel.cvut.cz> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2014-07-10Merge branch 'mc/doc-submodule-sync-recurse' into maintLibravatar Junio C Hamano1-1/+1
* mc/doc-submodule-sync-recurse: submodule: document "sync --recursive"
2014-06-13submodule: document "sync --recursive"Libravatar Matthew Chen1-1/+1
The "git submodule sync" command supports the --recursive flag, but the documentation does not mention this. That flag is useful, for example when a remote is changed in a submodule of a submodule. Signed-off-by: Matthew Chen <charlesmchen@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>