From 70c7ac22de681a83621bda03e676348170c8d8a2 Mon Sep 17 00:00:00 2001 From: Lars Hjemli Date: Sat, 26 May 2007 15:56:40 +0200 Subject: Add git-submodule command This command can be used to initialize, update and inspect submodules. It uses a .gitmodules file, readable by git-config, in the top level directory of the 'superproject' to specify a mapping between submodule paths and repository url. Example .gitmodules layout: [module "git"] url = git://git.kernel.org/pub/scm/git/git.git With this entry in .gitmodules (and a commit reference in the index entry for the path "git"), the command 'git submodule init' will clone the repository at kernel.org into the directory "git". Known issues ============ There is currently no way to override the url found in the .gitmodules file, except by manually creating the subproject repository. The place to fix this in the script has a rather long comment about a possible plan. Funny paths will be quoted in the output from git-ls-files, but git-submodule does not attempt to unquote (or even detect the presence of) such paths. Signed-off-by: Lars Hjemli Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 65 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 Documentation/git-submodule.txt (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt new file mode 100644 index 0000000000..cb0424f77b --- /dev/null +++ b/Documentation/git-submodule.txt @@ -0,0 +1,65 @@ +git-submodule(1) +================ + +NAME +---- +git-submodule - Initialize, update or inspect submodules + + +SYNOPSIS +-------- +'git-submodule' [--quiet] [--cached] [status|init|update] [--] [...] + + +COMMANDS +-------- +status:: + Show the status of the submodules. This will print the SHA-1 of the + currently checked out commit for each submodule, along with the + submodule path and the output of gitlink:git-describe[1] for the + SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not + initialized and `+` if the currently checked out submodule commit + does not match the SHA-1 found in the index of the containing + repository. This command is the default command for git-submodule. + +init:: + Initialize the submodules, i.e. clone the git repositories specified + in the .gitmodules file and checkout the submodule commits specified + in the index of the containing repository. This will make the + submodules HEAD be detached. + +update:: + Update the initialized submodules, i.e. checkout the submodule commits + specified in the index of the containing repository. This will make + the submodules HEAD be detached. + + +OPTIONS +------- +-q, --quiet:: + Only print error messages. + +--cached:: + Display the SHA-1 stored in the index, not the SHA-1 of the currently + checked out submodule commit. This option is only valid for the + status command. + +:: + Path to submodule(s). When specified this will restrict the command + to only operate on the submodules found at the specified paths. + +FILES +----- +When cloning submodules, a .gitmodules file in the top-level directory +of the containing repository is used to find the url of each submodule. +This file should be formatted in the same way as $GIR_DIR/config. The key +to each submodule url is "module.$path.url". + + +AUTHOR +------ +Written by Lars Hjemli + +GIT +--- +Part of the gitlink:git[7] suite -- cgit v1.2.3 From 211b7f19c7b046a6cadd36d54c549e4f335f0519 Mon Sep 17 00:00:00 2001 From: Lars Hjemli Date: Wed, 6 Jun 2007 11:13:02 +0200 Subject: git-submodule: clone during update, not during init This teaches 'git-submodule init' to register submodule paths and urls in .git/config instead of actually cloning them. The cloning is now handled as part of 'git-submodule update'. With this change it is possible to specify preferred/alternate urls for the submodules in .git/config before the submodules are cloned. Signed-off-by: Lars Hjemli Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index cb0424f77b..f8fb80f18b 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -23,15 +23,15 @@ status:: repository. This command is the default command for git-submodule. init:: - Initialize the submodules, i.e. clone the git repositories specified - in the .gitmodules file and checkout the submodule commits specified - in the index of the containing repository. This will make the - submodules HEAD be detached. + Initialize the submodules, i.e. register in .git/config each submodule + path and url found in .gitmodules. The key used in git/config is + `submodule.$path.url`. This command does not alter existing information + in .git/config. update:: - Update the initialized submodules, i.e. checkout the submodule commits - specified in the index of the containing repository. This will make - the submodules HEAD be detached. + Update the registered submodules, i.e. clone missing submodules and + checkout the commit specified in the index of the containing repository. + This will make the submodules HEAD be detached. OPTIONS @@ -50,7 +50,7 @@ OPTIONS FILES ----- -When cloning submodules, a .gitmodules file in the top-level directory +When initializing submodules, a .gitmodules file in the top-level directory of the containing repository is used to find the url of each submodule. This file should be formatted in the same way as $GIR_DIR/config. The key to each submodule url is "module.$path.url". -- cgit v1.2.3 From ecda072380e54084d5160d7b6a9cdb23369da804 Mon Sep 17 00:00:00 2001 From: Sven Verdoolaege Date: Sun, 24 Jun 2007 23:06:07 +0200 Subject: git-submodule: provide easy way of adding new submodules To make a submodule effectively usable, the path and a URL where the submodule can be cloned need to be stored in .gitmodules. This subcommand takes care of setting this information after cloning the new submodule. Only the index is updated, so, if needed, the user may still change the URL or switch to a different branch of the submodule before committing. Signed-off-by: Sven Verdoolaege Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index f8fb80f18b..7f0904e293 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -8,11 +8,19 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- +'git-submodule' [--quiet] [-b branch] add [] 'git-submodule' [--quiet] [--cached] [status|init|update] [--] [...] COMMANDS -------- +add:: + Add the given repository as a submodule at the given path + to the changeset to be committed next. In particular, the + repository is cloned at the specified path, added to the + changeset and registered in .gitmodules. If no path is + specified, the path is deduced from the repository specification. + status:: Show the status of the submodules. This will print the SHA-1 of the currently checked out commit for each submodule, along with the @@ -39,6 +47,9 @@ OPTIONS -q, --quiet:: Only print error messages. +-b, --branch:: + Branch of repository to add as submodule. + --cached:: Display the SHA-1 stored in the index, not the SHA-1 of the currently checked out submodule commit. This option is only valid for the -- cgit v1.2.3 From b2493649fe41f8a0db48ff4e809ea53c8a304a61 Mon Sep 17 00:00:00 2001 From: Matt Kraai Date: Fri, 6 Jul 2007 17:56:31 -0700 Subject: Add [verse] to the SYNOPSIS section of git-submodule.txt. The SYNOPSIS section of git-submodule.txt contains two forms. Since it doesn't use the verse style, the line boundary between them is not preserved and the second form can appear on the same line as the first form. Adding [verse] enables the verse style, which preserves the line boundary between them. Signed-off-by: Matt Kraai Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 7f0904e293..d76ae473bc 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -8,6 +8,7 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- +[verse] 'git-submodule' [--quiet] [-b branch] add [] 'git-submodule' [--quiet] [--cached] [status|init|update] [--] [...] -- cgit v1.2.3 From 813a0bd8a4b074f7ea0094c065b211873bd86c19 Mon Sep 17 00:00:00 2001 From: Lars Hjemli Date: Fri, 6 Jul 2007 19:38:38 +0200 Subject: git-submodule(1): update description and key names When git-submodule was updated to allow mapping between submodule name and submodule path, the documentation was left untouched. Signed-off-by: Lars Hjemli Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index d76ae473bc..2c48936fcd 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -33,8 +33,8 @@ status:: init:: Initialize the submodules, i.e. register in .git/config each submodule - path and url found in .gitmodules. The key used in git/config is - `submodule.$path.url`. This command does not alter existing information + name and url found in .gitmodules. The key used in .git/config is + `submodule.$name.url`. This command does not alter existing information in .git/config. update:: @@ -65,7 +65,7 @@ FILES When initializing submodules, a .gitmodules file in the top-level directory of the containing repository is used to find the url of each submodule. This file should be formatted in the same way as $GIR_DIR/config. The key -to each submodule url is "module.$path.url". +to each submodule url is "submodule.$name.url". AUTHOR -- cgit v1.2.3 From f31a522a2d64a5c7d83047e9234e1722ef63985e Mon Sep 17 00:00:00 2001 From: Mark Levedahl Date: Sun, 23 Sep 2007 22:19:42 -0400 Subject: git-submodule - allow a relative path as the subproject url This allows a subproject's location to be specified and stored as relative to the parent project's location (e.g., ./foo, or ../foo). This url is stored in .gitmodules as given. It is resolved into an absolute url by appending it to the parent project's url when the information is written to .git/config (i.e., during submodule add for the originator, and submodule init for a downstream recipient). This allows cloning of the project to work "as expected" if the project is hosted on a different server than when the subprojects were added. Signed-off-by: Mark Levedahl Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 3 +++ 1 file changed, 3 insertions(+) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2c48936fcd..335e973a6a 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -21,6 +21,9 @@ add:: repository is cloned at the specified path, added to the changeset and registered in .gitmodules. If no path is specified, the path is deduced from the repository specification. + If the repository url begins with ./ or ../, it is stored as + given but resolved as a relative path from the main project's + url when cloning. status:: Show the status of the submodules. This will print the SHA-1 of the -- cgit v1.2.3 From 6fbe42c7ee99b4cafa792b46a16b0158d305fe29 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 16 Dec 2007 22:03:21 -0800 Subject: Documentation/git-submodule: refer to gitmodules(5) Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 335e973a6a..3f59705686 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -68,7 +68,8 @@ FILES When initializing submodules, a .gitmodules file in the top-level directory of the containing repository is used to find the url of each submodule. This file should be formatted in the same way as $GIR_DIR/config. The key -to each submodule url is "submodule.$name.url". +to each submodule url is "submodule.$name.url". See gitlink:gitmodules[5] +for details. AUTHOR -- cgit v1.2.3 From c45857019c95ee8ffbf843bdb778ced0cfd4f6fb Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 27 Dec 2007 23:29:53 -0800 Subject: Documentation/git-submodule.txt: typofix Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 3f59705686..7d9a9fe5cd 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -67,7 +67,7 @@ FILES ----- When initializing submodules, a .gitmodules file in the top-level directory of the containing repository is used to find the url of each submodule. -This file should be formatted in the same way as $GIR_DIR/config. The key +This file should be formatted in the same way as `$GIT_DIR/config`. The key to each submodule url is "submodule.$name.url". See gitlink:gitmodules[5] for details. -- cgit v1.2.3 From 5162e69732d13dd079919a389a6ace8878aad716 Mon Sep 17 00:00:00 2001 From: Dan McGee Date: Sat, 29 Dec 2007 00:20:38 -0600 Subject: Documentation: rename gitlink macro to linkgit Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock Asciidoc configuration: @@ -149,7 +153,10 @@ # Inline macros. # Backslash prefix required for escape processing. # (?s) re flag for line spanning. -(?su)[\\]?(?P\w(\w|-)*?):(?P\S*?)(\[(?P.*?)\])= + +# Explicit so they can be nested. +(?su)[\\]?(?P(http|https|ftp|file|mailto|callto|image|link)):(?P\S*?)(\[(?P.*?)\])= + # Anchor: [[[id]]]. Bibliographic anchor. (?su)[\\]?\[\[\[(?P[\w][\w-]*?)\]\]\]=anchor3 # Anchor: [[id,xreflabel]] This default regex now matches explicit values, and unfortunately in this case gitlink was being matched by just 'link', causing the wrong inline macro template to be applied. By renaming the macro, we can avoid being matched by the wrong regex. Signed-off-by: Dan McGee Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 7d9a9fe5cd..cffc6d48fb 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -28,7 +28,7 @@ add:: status:: Show the status of the submodules. This will print the SHA-1 of the currently checked out commit for each submodule, along with the - submodule path and the output of gitlink:git-describe[1] for the + submodule path and the output of linkgit:git-describe[1] for the SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not initialized and `+` if the currently checked out submodule commit does not match the SHA-1 found in the index of the containing @@ -68,7 +68,7 @@ FILES When initializing submodules, a .gitmodules file in the top-level directory of the containing repository is used to find the url of each submodule. This file should be formatted in the same way as `$GIT_DIR/config`. The key -to each submodule url is "submodule.$name.url". See gitlink:gitmodules[5] +to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] for details. @@ -78,4 +78,4 @@ Written by Lars Hjemli GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite -- cgit v1.2.3 From c4a95c9f4b9c7b4dc8b705d323309263aa154e6a Mon Sep 17 00:00:00 2001 From: Steffen Prohaska Date: Mon, 21 Jan 2008 07:41:27 +0100 Subject: submodule: Document the details of the command line syntax Only "status" accepts "--cached" and the preferred way of passing sub-command specific options is after the sub-command. The documentation is adapted to reflect this. Signed-off-by: Steffen Prohaska Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index cffc6d48fb..e818e6e789 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,8 +9,9 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git-submodule' [--quiet] [-b branch] add [] -'git-submodule' [--quiet] [--cached] [status|init|update] [--] [...] +'git-submodule' [--quiet] add [-b branch] [--] [] +'git-submodule' [--quiet] status [--cached] [--] [...] +'git-submodule' [--quiet] [init|update] [--] [...] COMMANDS -- cgit v1.2.3 From d4264ca3233e206ea927bc94befda530683b5836 Mon Sep 17 00:00:00 2001 From: Mark Levedahl Date: Tue, 4 Mar 2008 20:15:02 -0500 Subject: git-submodule - Allow adding a submodule in-place When working in the top-level project, it is useful to create a new submodule as a git repo in a subdirectory, then add that submodule to the top-level in place. This patch allows "git submodule add subdir" to add the existing subdir to the current project. The presumption is the user will later push / clone the subdir to the so that future submodule init / updates will work. Absent this patch, "git submodule add" insists upon cloning the subdir from a repository at the given url, which is fine for adding an existing project in, but less useful when adding a new submodule from scratch to an existing project. The former functionality remains, and the clone is attempted if the subdir does not already exist as a valid git repo. Signed-off-by: Mark Levedahl Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index e818e6e789..b4d01605a5 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -18,8 +18,9 @@ COMMANDS -------- add:: Add the given repository as a submodule at the given path - to the changeset to be committed next. In particular, the - repository is cloned at the specified path, added to the + to the changeset to be committed next. If path is a valid + repository within the project, it is added as is. Otherwise, + repository is cloned at the specified path. path is added to the changeset and registered in .gitmodules. If no path is specified, the path is deduced from the repository specification. If the repository url begins with ./ or ../, it is stored as -- cgit v1.2.3 From 925e7f622d433e1cb2c7556acf8868bb30565a61 Mon Sep 17 00:00:00 2001 From: Ping Yin Date: Tue, 11 Mar 2008 21:52:18 +0800 Subject: git-submodule summary: documentation Signed-off-by: Ping Yin Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index e818e6e789..e96bf36521 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -12,6 +12,7 @@ SYNOPSIS 'git-submodule' [--quiet] add [-b branch] [--] [] 'git-submodule' [--quiet] status [--cached] [--] [...] 'git-submodule' [--quiet] [init|update] [--] [...] +'git-submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] COMMANDS @@ -46,6 +47,11 @@ update:: checkout the commit specified in the index of the containing repository. This will make the submodules HEAD be detached. +summary:: + Show commit summary between the given commit (defaults to HEAD) and + working tree/index. For a submodule in question, a series of commits + in the submodule between the given super project commit and the + index or working tree (switched by --cached) are shown. OPTIONS ------- @@ -56,9 +62,16 @@ OPTIONS Branch of repository to add as submodule. --cached:: - Display the SHA-1 stored in the index, not the SHA-1 of the currently - checked out submodule commit. This option is only valid for the - status command. + This option is only valid for status and summary commands. These + commands typically use the commit found in the submodule HEAD, but + with this option, the commit stored in the index is used instead. + +-n, --summary-limit:: + This option is only valid for the summary command. + Limit the summary size (number of commits shown in total). + Giving 0 will disable the summary; a negative number means unlimted + (the default). This limit only applies to modified submodules. The + size is always limited to 1 for added/deleted/typechanged submodules. :: Path to submodule(s). When specified this will restrict the command -- cgit v1.2.3 From 51836e9e125f67aa26724154757b4734c08057e4 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sat, 12 Apr 2008 18:34:39 -0700 Subject: Documentation/git-submodule: typofix Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 41f9f63566..6ffd896fbc 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -70,7 +70,7 @@ OPTIONS -n, --summary-limit:: This option is only valid for the summary command. Limit the summary size (number of commits shown in total). - Giving 0 will disable the summary; a negative number means unlimted + Giving 0 will disable the summary; a negative number means unlimited (the default). This limit only applies to modified submodules. The size is always limited to 1 for added/deleted/typechanged submodules. -- cgit v1.2.3 From be4d2c83b68a96285cc05036add4d64d324e52d9 Mon Sep 17 00:00:00 2001 From: Johannes Schindelin Date: Fri, 16 May 2008 11:23:03 +0100 Subject: submodule update: add convenience option --init When a submodule is not initialized and you do not want to change the defaults from .gitmodules anyway, you can now say $ git submodule update --init When "update" is called without --init on an uninitialized submodule, a hint to use --init is printed. Signed-off-by: Johannes Schindelin Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 6ffd896fbc..0668f295ee 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -11,7 +11,8 @@ SYNOPSIS [verse] 'git-submodule' [--quiet] add [-b branch] [--] [] 'git-submodule' [--quiet] status [--cached] [--] [...] -'git-submodule' [--quiet] [init|update] [--] [...] +'git-submodule' [--quiet] init [--] [...] +'git-submodule' [--quiet] update [--init] [--] [...] 'git-submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] @@ -47,6 +48,10 @@ update:: Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. This will make the submodules HEAD be detached. ++ +If the submodule is not yet initialized, and you just want to use the +setting as stored in .gitmodules, you can automatically initialize the +submodule with the --init option. summary:: Show commit summary between the given commit (defaults to HEAD) and -- cgit v1.2.3 From 9e1f0a85c68323830ea117092c55192b17aa3ac8 Mon Sep 17 00:00:00 2001 From: Christian Couder Date: Fri, 6 Jun 2008 09:07:32 +0200 Subject: documentation: move git(7) to git(1) As the "git" man page describes the "git" command at the end-user level, it seems better to move it to man section 1. Signed-off-by: Christian Couder Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 0668f295ee..139206f014 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -98,4 +98,4 @@ Written by Lars Hjemli GIT --- -Part of the linkgit:git[7] suite +Part of the linkgit:git[1] suite -- cgit v1.2.3 From 3240240ff427fa2e26a847c7c9fd89e6a4313daa Mon Sep 17 00:00:00 2001 From: Stephan Beyer Date: Sun, 8 Jun 2008 03:36:09 +0200 Subject: Docs: Use "-l::\n--long\n" format in OPTIONS sections The OPTIONS section of a documentation file contains a list of the options a git command accepts. Currently there are several variants to describe the case that different options (almost) do the same in the OPTIONS section. Some are: -f, --foo:: -f|--foo:: -f | --foo:: But AsciiDoc has the special form: -f:: --foo:: This patch applies this form to the documentation of the whole git suite, and removes useless em-dash prevention, so \--foo becomes --foo. Signed-off-by: Stephan Beyer Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 139206f014..441ae1483b 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -61,10 +61,12 @@ summary:: OPTIONS ------- --q, --quiet:: +-q:: +--quiet:: Only print error messages. --b, --branch:: +-b:: +--branch:: Branch of repository to add as submodule. --cached:: @@ -72,7 +74,8 @@ OPTIONS commands typically use the commit found in the submodule HEAD, but with this option, the commit stored in the index is used instead. --n, --summary-limit:: +-n:: +--summary-limit:: This option is only valid for the summary command. Limit the summary size (number of commits shown in total). Giving 0 will disable the summary; a negative number means unlimited -- cgit v1.2.3 From b1889c36d85514e5e70462294c561a02c2edfe2b Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Mon, 30 Jun 2008 01:09:04 -0500 Subject: Documentation: be consistent about "git-" versus "git " Since the git-* commands are not installed in $(bindir), using "git-command " in examples in the documentation is not a good idea. On the other hand, it is nice to be able to refer to each command using one hyphenated word. (There is no escaping it, anyway: man page names cannot have spaces in them.) This patch retains the dash in naming an operation, command, program, process, or action. Complete command lines that can be entered at a shell (i.e., without options omitted) are made to use the dashless form. The changes consist only of replacing some spaces with hyphens and vice versa. After a "s/ /-/g", the unpatched and patched versions are identical. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 441ae1483b..c1deec98d1 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,11 +9,11 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git-submodule' [--quiet] add [-b branch] [--] [] -'git-submodule' [--quiet] status [--cached] [--] [...] -'git-submodule' [--quiet] init [--] [...] -'git-submodule' [--quiet] update [--init] [--] [...] -'git-submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] +'git submodule' [--quiet] add [-b branch] [--] [] +'git submodule' [--quiet] status [--cached] [--] [...] +'git submodule' [--quiet] init [--] [...] +'git submodule' [--quiet] update [--init] [--] [...] +'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] COMMANDS -- cgit v1.2.3 From 483bc4f045881b998512ae814d6cf44d0c0cb493 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Mon, 30 Jun 2008 13:56:34 -0500 Subject: Documentation formatting and cleanup Following what appears to be the predominant style, format names of commands and commandlines both as `teletype text`. While we're at it, add articles ("a" and "the") in some places, italicize the name of the command in the manual page synopsis line, and add a comma or two where it seems appropriate. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index c1deec98d1..9c4052c58a 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -32,11 +32,11 @@ add:: status:: Show the status of the submodules. This will print the SHA-1 of the currently checked out commit for each submodule, along with the - submodule path and the output of linkgit:git-describe[1] for the + submodule path and the output of `git-describe` for the SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not initialized and `+` if the currently checked out submodule commit does not match the SHA-1 found in the index of the containing - repository. This command is the default command for git-submodule. + repository. This command is the default command for `git-submodule`. init:: Initialize the submodules, i.e. register in .git/config each submodule -- cgit v1.2.3 From ba020ef5eb5fca3d757bd580ff117adaf81ca079 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Thu, 3 Jul 2008 00:41:41 -0500 Subject: manpages: italicize git command names (which were in teletype font) The names of git commands are not meant to be entered at the commandline; they are just names. So we render them in italics, as is usual for command names in manpages. Using doit () { perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }' } for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \ merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt do doit <"$i" >"$i+" && mv "$i+" "$i" done git diff . Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 9c4052c58a..105fc2dcdc 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -32,11 +32,11 @@ add:: status:: Show the status of the submodules. This will print the SHA-1 of the currently checked out commit for each submodule, along with the - submodule path and the output of `git-describe` for the + submodule path and the output of 'git-describe' for the SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not initialized and `+` if the currently checked out submodule commit does not match the SHA-1 found in the index of the containing - repository. This command is the default command for `git-submodule`. + repository. This command is the default command for 'git-submodule'. init:: Initialize the submodules, i.e. register in .git/config each submodule -- cgit v1.2.3 From ec05df353c594f2afc6509831d3ce145856b0b89 Mon Sep 17 00:00:00 2001 From: Mark Levedahl Date: Wed, 9 Jul 2008 21:05:40 -0400 Subject: git-submodule - make "submodule add" more strict, and document it This change makes "submodule add" much more strict in the arguments it takes, and is intended to address confusion as recently noted on the git-list. With this change, the required syntax is: $ git submodule add URL path Specifically, this eliminates the form $ git submodule add URL which was confused by more than one person as $ git submodule add path With this patch, the URL locating the submodule's origin repository can be either an absolute URL, or (if it begins with ./ or ../) can express the submodule's repository location relative to the superproject's origin. This patch also eliminates a third form of URL, which was relative to the superproject's top-level directory (not its repository). Any URL that was neither absolute nor matched ./*|../* was assumed to point to a subdirectory of the superproject as the location of the submodule's origin repository. This URL form was confusing and does not seem to correspond to an important use-case. Specifically, no-one has identified the need to clone from a repository already in the superproject's tree, but if this is needed it is easily done using an absolute URL: $(pwd)/relative-path. So, no functionality is lost with this patch. (t6008-rev-list-submodule.sh did rely upon this relative URL, fixed by using $(pwd).) Following this change, there are exactly four variants of submodule-add, as both arguments have two flavors: URL can be absolute, or can begin with ./|../ and thus names the submodule's origin relative to the superproject's origin. Note: With this patch, "submodule add" discerns an absolute URL as matching /*|*:*: e.g., URL begins with /, or it contains a :. This works for all valid URLs, an absolute path in POSIX, as well as an absolute path on Windows). path can either already exist as a valid git repo, or will be cloned from the given URL. The first form here eases creation of a new submodule in an existing superproject as the submodule can be added and tested in-tree before pushing to the public repository. However, the more usual form is the second, where the repo is cloned from the given URL. This specifically addresses the issue of $ git submodule add a/b/c attempting to clone from a repository at "a/b/c" to create a new module in "c". This also simplifies description of "relative URL" as there is now exactly *one* form: a URL relative to the parent's origin repo. Signed-off-by: Mark Levedahl Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 105fc2dcdc..76702a0a5a 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,7 +9,7 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git submodule' [--quiet] add [-b branch] [--] [] +'git submodule' [--quiet] add [-b branch] [--] 'git submodule' [--quiet] status [--cached] [--] [...] 'git submodule' [--quiet] init [--] [...] 'git submodule' [--quiet] update [--init] [--] [...] @@ -20,14 +20,31 @@ COMMANDS -------- add:: Add the given repository as a submodule at the given path - to the changeset to be committed next. If path is a valid - repository within the project, it is added as is. Otherwise, - repository is cloned at the specified path. path is added to the - changeset and registered in .gitmodules. If no path is - specified, the path is deduced from the repository specification. - If the repository url begins with ./ or ../, it is stored as - given but resolved as a relative path from the main project's - url when cloning. + to the changeset to be committed next to the current + project: the current project is termed termed the "superproject". ++ +This requires two arguments: and . ++ + is the URL of the new submodule's origin repository. +This may be either an absolute URL, or (if it begins with ./ +or ../), the location relative to the superproject's origin +repository. ++ + is the relative location for the cloned submodule to +exist in the superproject. If does not exist, then the +submodule is created by cloning from the named URL. If does +exist and is already a valid git repository, then this is added +to the changeset without cloning. This second form is provided +to ease creating a new submodule from scratch, and presumes +the user will later push the submodule to the given URL. ++ +In either case, the given URL is recorded into .gitmodules for +use by subsequent users cloning the superproject. If the URL is +given relative to the superproject's repository, the presumption +is the superproject and submodule repositories will be kept +together in the same relative location, and only the +superproject's URL need be provided: git-submodule will correctly +locate the submodule using the relative URL in .gitmodules. status:: Show the status of the submodules. This will print the SHA-1 of the @@ -85,6 +102,7 @@ OPTIONS :: Path to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. + (This argument is required with add). FILES ----- -- cgit v1.2.3 From e38953ab00bfb150822d2d92d2dc8e4ce31ef9a4 Mon Sep 17 00:00:00 2001 From: Petr Baudis Date: Wed, 16 Jul 2008 20:44:12 +0200 Subject: Documentation/git-submodule.txt: Add Description section Figuring out how submodules work conceptually is quite a bumpy ride for a newcomer; the user manual helps (if one knows to actually look into it), but the reference documentation should provide good quick intro as well. This patch attempts to do that, with suggestions from Heikki Orsila. Cc: Heikki Orsila Signed-off-by: Petr Baudis Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 76702a0a5a..bb4e6fbf59 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -16,6 +16,28 @@ SYNOPSIS 'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] +DESCRIPTION +----------- +Submodules are a special kind of tree entries which refer to a particular tree +state in another repository. The tree entry describes +the existence of a submodule with the given name and the exact revision that +should be used, while an entry in `.gitmodules` file gives the location of +the repository. + +When checked out, submodules will maintain their own independent repositories +within their directories; the only link between the submodule and the "parent +project" is the tree entry within the parent project mentioned above. + +This command will manage the tree entries and contents of the gitmodules file +for you, as well as inspecting the status of your submodules and updating them. +When adding a new submodule to the tree, the 'add' subcommand is to be used. +However, when pulling a tree containing submodules, these will not be checked +out by default; the 'init' and 'update' subcommands will maintain submodules +checked out and at appropriate revision in your working tree. You can inspect +the current status of your submodules using the 'submodule' subcommand and get +an overview of changes 'update' would perform using the 'summary' subcommand. + + COMMANDS -------- add:: -- cgit v1.2.3 From c47f10246ac6413ac6902bd70e45492174fac873 Mon Sep 17 00:00:00 2001 From: Petr Baudis Date: Fri, 18 Jul 2008 15:40:41 +0200 Subject: Documentation/git-submodule.txt: Further clarify the description This patch rewrites the general description yet again, first clarifying the high-level concept, mentioning the difference to remotes and using the subtree merge strategy, then getting to the details about tree entries and .gitmodules file. The patch also makes few smallar grammar fixups within the rest of the description and clarifies how does 'init' relate to 'update --init'. Cc: Heikki Orsila Signed-off-by: Petr Baudis Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 69 ++++++++++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 22 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index bb4e6fbf59..829b03201d 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -18,24 +18,44 @@ SYNOPSIS DESCRIPTION ----------- -Submodules are a special kind of tree entries which refer to a particular tree -state in another repository. The tree entry describes -the existence of a submodule with the given name and the exact revision that -should be used, while an entry in `.gitmodules` file gives the location of -the repository. - -When checked out, submodules will maintain their own independent repositories -within their directories; the only link between the submodule and the "parent -project" is the tree entry within the parent project mentioned above. - -This command will manage the tree entries and contents of the gitmodules file -for you, as well as inspecting the status of your submodules and updating them. -When adding a new submodule to the tree, the 'add' subcommand is to be used. -However, when pulling a tree containing submodules, these will not be checked -out by default; the 'init' and 'update' subcommands will maintain submodules -checked out and at appropriate revision in your working tree. You can inspect -the current status of your submodules using the 'submodule' subcommand and get -an overview of changes 'update' would perform using the 'summary' subcommand. +Submodules allow foreign repositories to be embedded within +a dedicated subdirectory of the source tree, always pointed +at a particular commit. + +They are not to be confused with remotes, which are meant mainly +for branches of the same project; submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the 'subtree' merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route. + +Submodules are composed from a so-called `gitlink` tree entry +in the main repository that refers to a particular commit object +within the inner repository that is completely separate. +A record in the `.gitmodules` file at the root of the source +tree assigns a logical name to the submodule and describes +the default URL the submodule shall be cloned from. +The logical name can be used for overriding this URL within your +local repository configuration (see 'submodule init'). + +This command will manage the tree entries and contents of the +gitmodules file for you, as well as inspect the status of your +submodules and update them. +When adding a new submodule to the tree, the 'add' subcommand +is to be used. However, when pulling a tree containing submodules, +these will not be checked out by default; +the 'init' and 'update' subcommands will maintain submodules +checked out and at appropriate revision in your working tree. +You can briefly inspect the up-to-date status of your submodules +using the 'status' subcommand and get a detailed overview of the +difference between the index and checkouts using the 'summary' +subcommand. COMMANDS @@ -78,10 +98,15 @@ status:: repository. This command is the default command for 'git-submodule'. init:: - Initialize the submodules, i.e. register in .git/config each submodule - name and url found in .gitmodules. The key used in .git/config is - `submodule.$name.url`. This command does not alter existing information - in .git/config. + Initialize the submodules, i.e. register each submodule name + and url found in .gitmodules into .git/config. + The key used in .git/config is `submodule.$name.url`. + This command does not alter existing information in .git/config. + You can then customize the submodule clone URLs in .git/config + for your local setup and proceed to 'git submodule update'; + you can also just use 'git submodule update --init' without + the explicit 'init' step if you do not intend to customize + any submodule locations. update:: Update the registered submodules, i.e. clone missing submodules and -- cgit v1.2.3 From 77ef80a83e652d65a26213bc276b33051524998f Mon Sep 17 00:00:00 2001 From: Cesar Eduardo Barros Date: Sat, 26 Jul 2008 01:17:42 -0300 Subject: Documentation/git-submodule.txt: fix doubled word Signed-off-by: Cesar Eduardo Barros Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 829b03201d..35efeefb30 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -63,7 +63,7 @@ COMMANDS add:: Add the given repository as a submodule at the given path to the changeset to be committed next to the current - project: the current project is termed termed the "superproject". + project: the current project is termed the "superproject". + This requires two arguments: and . + -- cgit v1.2.3 From f448e24e2fe336621306b04b84e947bdd04f7ecc Mon Sep 17 00:00:00 2001 From: Abhijit Menon-Sen Date: Wed, 30 Jul 2008 15:03:43 +0530 Subject: Make the DESCRIPTION match ... items in the SYNOPSIS When the SYNOPSIS says e.g. "...", it is nice if the DESCRIPTION also mentions "..." and says the specified "paths" (note plural) are used for $whatever. This fixes the obvious mismatches. Signed-off-by: Abhijit Menon-Sen Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 35efeefb30..bf33b0cba0 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -146,8 +146,8 @@ OPTIONS (the default). This limit only applies to modified submodules. The size is always limited to 1 for added/deleted/typechanged submodules. -:: - Path to submodule(s). When specified this will restrict the command +...:: + Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. (This argument is required with add). -- cgit v1.2.3 From 19a31f9c1a6b18abd8a7f20d616516afca36a6a3 Mon Sep 17 00:00:00 2001 From: Mark Levedahl Date: Sun, 10 Aug 2008 19:10:04 -0400 Subject: git-submodule - Add 'foreach' subcommand submodule foreach will execute the list of commands in each currently checked out submodule directory. The list of commands is arbitrary as long as it is acceptable to sh. The variables '$path' and '$sha1' are availble to the command-list, defining the submodule path relative to the superproject and the submodules's commitID as recorded in the superproject (this may be different than HEAD in the submodule). This utility is inspired by a number of threads on the mailing list looking for ways to better integrate submodules in a tree and work with them as a unit. This could include fetching a new branch in each from a given source, or possibly checking out a given named branch in each. Currently, there is no consensus as to what additional commands should be implemented in the porcelain, requiring all users whose needs exceed that of git-submodule to do their own scripting. The foreach command is intended to support such scripting, and in particular does no error checking and produces no output, thus allowing end users complete control over any information printed out and over what constitutes an error. The processing does terminate if the command-list returns an error, but processing can easily be forced for all submodules be terminating the list with ';true'. Signed-off-by: Mark Levedahl Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index bf33b0cba0..abbd5b72de 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -14,6 +14,7 @@ SYNOPSIS 'git submodule' [--quiet] init [--] [...] 'git submodule' [--quiet] update [--init] [--] [...] 'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] +'git submodule' [--quiet] foreach DESCRIPTION @@ -123,6 +124,22 @@ summary:: in the submodule between the given super project commit and the index or working tree (switched by --cached) are shown. +foreach:: + Evaluates an arbitrary shell command in each checked out submodule. + The command has access to the variables $path and $sha1: + $path is the name of the submodule directory relative to the + superproject, and $sha1 is the commit as recorded in the superproject. + Any submodules defined in the superproject but not checked out are + ignored by this command. Unless given --quiet, foreach prints the name + of each submodule before evaluating the command. + A non-zero return from the command in any submodule causes + the processing to terminate. This can be overridden by adding '|| :' + to the end of the command. ++ +As an example, "git submodule foreach 'echo $path `git rev-parse HEAD`' will +show the path and currently checked out commit for each submodule. + + OPTIONS ------- -q:: -- cgit v1.2.3 From 2327f61ecc4e9fbb6dd9fffdec0b043aeaca908f Mon Sep 17 00:00:00 2001 From: David Aguilar Date: Sun, 24 Aug 2008 12:43:37 -0700 Subject: git-submodule: add "sync" command When a submodule's URL changes upstream, existing submodules will be out of sync since their remote."$origin".url will still be set to the old value. This adds a "git submodule sync" command that reads submodules' URLs from .gitmodules and updates them accordingly. Signed-off-by: David Aguilar Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index abbd5b72de..babaa9bc46 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -15,6 +15,7 @@ SYNOPSIS 'git submodule' [--quiet] update [--init] [--] [...] 'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] 'git submodule' [--quiet] foreach +'git submodule' [--quiet] sync [--] [...] DESCRIPTION @@ -139,6 +140,14 @@ foreach:: As an example, "git submodule foreach 'echo $path `git rev-parse HEAD`' will show the path and currently checked out commit for each submodule. +sync:: + Synchronizes submodules' remote URL configuration setting + to the value specified in .gitmodules. This is useful when + submodule URLs change upstream and you need to update your local + repositories accordingly. ++ +"git submodule sync" synchronizes all submodules while +"git submodule sync -- A" synchronizes submodule "A" only. OPTIONS ------- -- cgit v1.2.3 From 04c8ce9c1c803a8dc0f3728f57550f9bc9e605c2 Mon Sep 17 00:00:00 2001 From: Markus Heidelberg Date: Fri, 19 Dec 2008 13:14:18 +0100 Subject: Documentation: fix typos, grammar, asciidoc syntax Signed-off-by: Markus Heidelberg Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index bf33b0cba0..e6652a7de1 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -85,7 +85,7 @@ use by subsequent users cloning the superproject. If the URL is given relative to the superproject's repository, the presumption is the superproject and submodule repositories will be kept together in the same relative location, and only the -superproject's URL need be provided: git-submodule will correctly +superproject's URL needs to be provided: git-submodule will correctly locate the submodule using the relative URL in .gitmodules. status:: -- cgit v1.2.3 From 31ca3ac30fe3c2583881a74ef346911c8fba478f Mon Sep 17 00:00:00 2001 From: Fabian Franz Date: Thu, 5 Feb 2009 20:18:32 -0200 Subject: submodule: add --no-fetch parameter to update command git submodule update --no-fetch makes it possible to use git submodule update in complete offline mode by not fetching new revisions. This does make sense in the following setup: * There is an unstable and a stable branch in the super/master repository. * The submodules might be at different revisions in the branches. * You are at some place without internet connection ;) With this patch it is now possible to change branches and update the submodules to be at the recorded revision without online access. Another advantage is that with -N the update operation is faster, because fetch is checking for new updates even if there was no fetch/pull on the super/master repository since the last update. Signed-off-by: Fabian Franz Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2f207fbbda..3b8df44673 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git submodule' [--quiet] add [-b branch] [--] 'git submodule' [--quiet] status [--cached] [--] [...] 'git submodule' [--quiet] init [--] [...] -'git submodule' [--quiet] update [--init] [--] [...] +'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--] [...] 'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] 'git submodule' [--quiet] foreach 'git submodule' [--quiet] sync [--] [...] @@ -172,6 +172,11 @@ OPTIONS (the default). This limit only applies to modified submodules. The size is always limited to 1 for added/deleted/typechanged submodules. +-N:: +--no-fetch:: + This option is only valid for the update command. + Don't fetch new objects from the remote site. + ...:: Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. -- cgit v1.2.3 From ca2cedba70e9356a1a20b0e39acd07ab92fee80e Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Fri, 24 Apr 2009 09:06:38 +1000 Subject: git-submodule: add support for --rebase. 'git submodule update --rebase' rebases your local branch on top of what would have been checked out to a detached HEAD otherwise. In some cases, detaching the HEAD when updating a submodule complicates the workflow to commit to this submodule (checkout master, rebase, then commit). For submodules that require frequent updates but infrequent (if any) commits, a rebase can be executed directly by the git-submodule command, ensuring that the submodules stay on their respective branches. git-config key: submodule.$name.rebase (bool) Signed-off-by: Peter Hutterer Signed-off-by: Johannes Schindelin Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 3b8df44673..0286409744 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git submodule' [--quiet] add [-b branch] [--] 'git submodule' [--quiet] status [--cached] [--] [...] 'git submodule' [--quiet] init [--] [...] -'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--] [...] +'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] [--] [...] 'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] 'git submodule' [--quiet] foreach 'git submodule' [--quiet] sync [--] [...] @@ -113,7 +113,8 @@ init:: update:: Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. - This will make the submodules HEAD be detached. + This will make the submodules HEAD be detached unless '--rebase' is + specified or the key `submodule.$name.rebase` is set to `true`. + If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the @@ -177,6 +178,15 @@ OPTIONS This option is only valid for the update command. Don't fetch new objects from the remote site. +--rebase:: + This option is only valid for the update command. + Rebase the current branch onto the commit recorded in the + superproject. If this option is given, the submodule's HEAD will not + be detached. If a a merge failure prevents this process, you will have + to resolve these failures with linkgit:git-rebase[1]. + If the key `submodule.$name.rebase` is set to `true`, this option is + implicit. + ...:: Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. -- cgit v1.2.3 From d92a39590d1126e195f1bbccf182a2cdb79218e7 Mon Sep 17 00:00:00 2001 From: "Michael S. Tsirkin" Date: Mon, 4 May 2009 22:30:01 +0300 Subject: Add --reference option to git submodule. This adds --reference option to git submodule add and git submodule update commands, which is passed to git clone. Signed-off-by: Michael S. Tsirkin Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 3b8df44673..14256c695b 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,10 +9,12 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git submodule' [--quiet] add [-b branch] [--] +'git submodule' [--quiet] add [-b branch] + [--reference ] [--] 'git submodule' [--quiet] status [--cached] [--] [...] 'git submodule' [--quiet] init [--] [...] -'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--] [...] +'git submodule' [--quiet] update [--init] [-N|--no-fetch] + [--reference ] [--] [...] 'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] 'git submodule' [--quiet] foreach 'git submodule' [--quiet] sync [--] [...] @@ -177,6 +179,14 @@ OPTIONS This option is only valid for the update command. Don't fetch new objects from the remote site. +--reference :: + This option is only valid for add and update commands. These + commands sometimes need to clone a remote repository. In this case, + this option will be passed to the linkgit:git-clone[1] command. ++ +*NOTE*: Do *not* use this option unless you have read the note +for linkgit:git-clone[1]'s --reference and --shared options carefully. + ...:: Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. -- cgit v1.2.3 From 329484256e0fe42676e93669122e7a5a007ef4ed Mon Sep 17 00:00:00 2001 From: Johan Herland Date: Wed, 3 Jun 2009 08:27:06 +0200 Subject: Rename submodule..rebase to submodule..update The addition of "submodule..rebase" demonstrates the usefulness of alternatives to the default behaviour of "git submodule update". However, by naming the config variable "submodule..rebase", and making it a boolean choice, we are artificially constraining future git versions that may want to add _more_ alternatives than just "rebase". Therefore, while "submodule..rebase" is not yet in a stable git release, future-proof it, by changing it from submodule..rebase = true/false to submodule..update = rebase/checkout where "checkout" specifies the default behaviour of "git submodule update" (checking out the new commit to a detached HEAD), and "rebase" specifies the --rebase behaviour (where the current local branch in the submodule is rebase onto the new commit). Thus .update == checkout is equivalent to .rebase == false, and .update == rebase is equivalent to .rebase == true. Finally, leaving .update unset is equivalent to leaving .rebase unset. In future git versions, other alternatives to "git submodule update" behaviour can be included by adding them to the list of allowable values for the submodule..update variable. Signed-off-by: Johan Herland Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 0286409744..f993469dc6 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -114,7 +114,7 @@ update:: Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. This will make the submodules HEAD be detached unless '--rebase' is - specified or the key `submodule.$name.rebase` is set to `true`. + specified or the key `submodule.$name.update` is set to `rebase`. + If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the @@ -184,7 +184,7 @@ OPTIONS superproject. If this option is given, the submodule's HEAD will not be detached. If a a merge failure prevents this process, you will have to resolve these failures with linkgit:git-rebase[1]. - If the key `submodule.$name.rebase` is set to `true`, this option is + If the key `submodule.$name.update` is set to `rebase`, this option is implicit. ...:: -- cgit v1.2.3 From 42b491786260eb17d97ea9fb1c4b70075bca9523 Mon Sep 17 00:00:00 2001 From: Johan Herland Date: Wed, 3 Jun 2009 00:59:12 +0200 Subject: git-submodule: add support for --merge. 'git submodule update --merge' merges the commit referenced by the superproject into your local branch, instead of checking it out on a detached HEAD. As evidenced by the addition of "git submodule update --rebase", it is useful to provide alternatives to the default 'checkout' behaviour of "git submodule update". One such alternative is, when updating a submodule to a new commit, to merge that commit into the current local branch in that submodule. This is useful in workflows where you want to update your submodule from its upstream, but you cannot use --rebase, because you have downstream people working on top of your submodule branch, and you don't want to disrupt their work. Signed-off-by: Johan Herland Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index f993469dc6..2289d11f0e 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -113,8 +113,9 @@ init:: update:: Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. - This will make the submodules HEAD be detached unless '--rebase' is - specified or the key `submodule.$name.update` is set to `rebase`. + This will make the submodules HEAD be detached unless '--rebase' or + '--merge' is specified or the key `submodule.$name.update` is set to + `rebase` or `merge`. + If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the @@ -187,6 +188,16 @@ OPTIONS If the key `submodule.$name.update` is set to `rebase`, this option is implicit. +--merge:: + This option is only valid for the update command. + Merge the commit recorded in the superproject into the current branch + of the submodule. If this option is given, the submodule's HEAD will + not be detached. If a merge failure prevents this process, you will + have to resolve the resulting conflicts within the submodule with the + usual conflict resolution tools. + If the key `submodule.$name.update` is set to `merge`, this option is + implicit. + ...:: Paths to submodule(s). When specified this will restrict the command to only operate on the submodules found at the specified paths. -- cgit v1.2.3 From 1c3acfcd575cdd1bfc9981baf5782eb5cf433362 Mon Sep 17 00:00:00 2001 From: Miklos Vajna Date: Sun, 28 Jun 2009 14:55:45 +0200 Subject: git-submodule documentation: fix foreach example Backtick and apostrophe are asciidoc markup, so they should be escaped in order to get the expected result in the rendered manual page. Signed-off-by: Miklos Vajna Signed-off-by: Junio C Hamano --- Documentation/git-submodule.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'Documentation/git-submodule.txt') diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 3b8df44673..15b34d3760 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -137,8 +137,9 @@ foreach:: the processing to terminate. This can be overridden by adding '|| :' to the end of the command. + -As an example, "git submodule foreach 'echo $path `git rev-parse HEAD`' will -show the path and currently checked out commit for each submodule. +As an example, +git submodule foreach \'echo $path {backtick}git +rev-parse HEAD{backtick}'+ will show the path and currently checked out +commit for each submodule. sync:: Synchronizes submodules' remote URL configuration setting -- cgit v1.2.3