mirror of
https://github.com/git/git.git
synced 2024-05-24 00:16:31 +02:00
f0a96e8d4c
When `remote.<name>.branch` is not configured, `git submodule update` currently falls back to using the branch name `master`. A much better idea, however, is to use the remote `HEAD`: on all Git servers running reasonably recent Git versions, the symref `HEAD` points to the main branch. Note: t7419 demonstrates that there _might_ be use cases out there that _expect_ `git submodule update --remote` to update submodules to the remote `master` branch even if the remote `HEAD` points to another branch. Arguably, this patch makes the behavior more intuitive, but there is a slight possibility that this might cause regressions in obscure setups. Even so, it should be okay to fix this behavior without anything like a longer transition period: - The `git submodule update --remote` command is not really common. - Current Git's behavior when running this command is outright confusing, unless the remote repository's current branch _is_ `master` (in which case the proposed behavior matches the old behavior). - If a user encounters a regression due to the changed behavior, the fix is actually trivial: setting `submodule.<name>.branch` to `master` will reinstate the old behavior. Helped-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
128 lines
4.4 KiB
Plaintext
128 lines
4.4 KiB
Plaintext
gitmodules(5)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
gitmodules - Defining submodule properties
|
|
|
|
SYNOPSIS
|
|
--------
|
|
$GIT_WORK_DIR/.gitmodules
|
|
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
The `.gitmodules` file, located in the top-level directory of a Git
|
|
working tree, is a text file with a syntax matching the requirements
|
|
of linkgit:git-config[1].
|
|
|
|
The file contains one subsection per submodule, and the subsection value
|
|
is the name of the submodule. The name is set to the path where the
|
|
submodule has been added unless it was customized with the `--name`
|
|
option of 'git submodule add'. Each submodule section also contains the
|
|
following required keys:
|
|
|
|
submodule.<name>.path::
|
|
Defines the path, relative to the top-level directory of the Git
|
|
working tree, where the submodule is expected to be checked out.
|
|
The path name must not end with a `/`. All submodule paths must
|
|
be unique within the .gitmodules file.
|
|
|
|
submodule.<name>.url::
|
|
Defines a URL from which the submodule repository can be cloned.
|
|
This may be either an absolute URL ready to be passed to
|
|
linkgit:git-clone[1] or (if it begins with ./ or ../) a location
|
|
relative to the superproject's origin repository.
|
|
|
|
In addition, there are a number of optional keys:
|
|
|
|
submodule.<name>.update::
|
|
Defines the default update procedure for the named submodule,
|
|
i.e. how the submodule is updated by "git submodule update"
|
|
command in the superproject. This is only used by `git
|
|
submodule init` to initialize the configuration variable of
|
|
the same name. Allowed values here are 'checkout', 'rebase',
|
|
'merge' or 'none'. See description of 'update' command in
|
|
linkgit:git-submodule[1] for their meaning. For security
|
|
reasons, the '!command' form is not accepted here.
|
|
|
|
submodule.<name>.branch::
|
|
A remote branch name for tracking updates in the upstream submodule.
|
|
If the option is not specified, it defaults to the remote 'HEAD'.
|
|
A special value of `.` is used to indicate that the name of the branch
|
|
in the submodule should be the same name as the current branch in the
|
|
current repository. See the `--remote` documentation in
|
|
linkgit:git-submodule[1] for details.
|
|
|
|
submodule.<name>.fetchRecurseSubmodules::
|
|
This option can be used to control recursive fetching of this
|
|
submodule. If this option is also present in the submodules entry in
|
|
.git/config of the superproject, the setting there will override the
|
|
one found in .gitmodules.
|
|
Both settings can be overridden on the command line by using the
|
|
"--[no-]recurse-submodules" option to "git fetch" and "git pull".
|
|
|
|
submodule.<name>.ignore::
|
|
Defines under what circumstances "git status" and the diff family show
|
|
a submodule as modified. The following values are supported:
|
|
+
|
|
--
|
|
all;; The submodule will never be considered modified (but will
|
|
nonetheless show up in the output of status and commit when it has
|
|
been staged).
|
|
|
|
dirty;; All changes to the submodule's work tree will be ignored, only
|
|
committed differences between the HEAD of the submodule and its
|
|
recorded state in the superproject are taken into account.
|
|
|
|
untracked;; Only untracked files in submodules will be ignored.
|
|
Committed differences and modifications to tracked files will show
|
|
up.
|
|
|
|
none;; No modifications to submodules are ignored, all of committed
|
|
differences, and modifications to tracked and untracked files are
|
|
shown. This is the default option.
|
|
|
|
If this option is also present in the submodules entry in .git/config
|
|
of the superproject, the setting there will override the one found in
|
|
.gitmodules.
|
|
|
|
Both settings can be overridden on the command line by using the
|
|
"--ignore-submodules" option. The 'git submodule' commands are not
|
|
affected by this setting.
|
|
--
|
|
|
|
submodule.<name>.shallow::
|
|
When set to true, a clone of this submodule will be performed as a
|
|
shallow clone (with a history depth of 1) unless the user explicitly
|
|
asks for a non-shallow clone.
|
|
|
|
|
|
EXAMPLES
|
|
--------
|
|
|
|
Consider the following .gitmodules file:
|
|
|
|
----
|
|
[submodule "libfoo"]
|
|
path = include/foo
|
|
url = git://foo.com/git/lib.git
|
|
|
|
[submodule "libbar"]
|
|
path = include/bar
|
|
url = git://bar.com/git/lib.git
|
|
----
|
|
|
|
This defines two submodules, `libfoo` and `libbar`. These are expected to
|
|
be checked out in the paths `include/foo` and `include/bar`, and for both
|
|
submodules a URL is specified which can be used for cloning the submodules.
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkgit:git-submodule[1], linkgit:gitsubmodules[7], linkgit:git-config[1]
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|