summaryrefslogtreecommitdiff
path: root/Documentation/git-submodule.txt
diff options
context:
space:
mode:
authorLars Hjemli <hjemli@gmail.com>2007-05-26 13:56:40 (GMT)
committerJunio C Hamano <junkio@cox.net>2007-05-27 03:24:07 (GMT)
commit70c7ac22de681a83621bda03e676348170c8d8a2 (patch)
tree604b5ea434354562c978a5ce479c95af0c147118 /Documentation/git-submodule.txt
parent99b5a79e1329468bee26ae3bd9070c47418279d0 (diff)
downloadgit-70c7ac22de681a83621bda03e676348170c8d8a2.zip
git-70c7ac22de681a83621bda03e676348170c8d8a2.tar.gz
git-70c7ac22de681a83621bda03e676348170c8d8a2.tar.bz2
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 <hjemli@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
Diffstat (limited to 'Documentation/git-submodule.txt')
-rw-r--r--Documentation/git-submodule.txt65
1 files changed, 65 insertions, 0 deletions
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
new file mode 100644
index 0000000..cb0424f
--- /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] [--] [<path>...]
+
+
+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>::
+ 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 <hjemli@gmail.com>
+
+GIT
+---
+Part of the gitlink:git[7] suite