| 1 | gitmodules(5) |
| 2 | ============= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | gitmodules - Defining submodule properties |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | $GIT_WORK_TREE/.gitmodules |
| 11 | |
| 12 | |
| 13 | DESCRIPTION |
| 14 | ----------- |
| 15 | |
| 16 | The `.gitmodules` file, located in the top-level directory of a Git |
| 17 | working tree, is a text file with a syntax matching the requirements |
| 18 | of linkgit:git-config[1]. |
| 19 | |
| 20 | The file contains one subsection per submodule, and the subsection value |
| 21 | is the name of the submodule. The name is set to the path where the |
| 22 | submodule has been added unless it was customized with the `--name` |
| 23 | option of 'git submodule add'. Each submodule section also contains the |
| 24 | following required keys: |
| 25 | |
| 26 | submodule.<name>.path:: |
| 27 | Defines the path, relative to the top-level directory of the Git |
| 28 | working tree, where the submodule is expected to be checked out. |
| 29 | The path name must not end with a `/`. All submodule paths must |
| 30 | be unique within the `.gitmodules` file. |
| 31 | |
| 32 | submodule.<name>.url:: |
| 33 | Defines a URL from which the submodule repository can be cloned. |
| 34 | This may be either an absolute URL ready to be passed to |
| 35 | linkgit:git-clone[1] or (if it begins with `./` or `../`) a location |
| 36 | relative to the superproject's origin repository. |
| 37 | |
| 38 | In addition, there are a number of optional keys: |
| 39 | |
| 40 | submodule.<name>.update:: |
| 41 | Defines the default update procedure for the named submodule, |
| 42 | i.e. how the submodule is updated by the `git submodule update` |
| 43 | command in the superproject. This is only used by `git |
| 44 | submodule init` to initialize the configuration variable of |
| 45 | the same name. Allowed values here are 'checkout', 'rebase', |
| 46 | 'merge' or 'none', but not '!command' (for security reasons). |
| 47 | See the description of the 'update' command in |
| 48 | linkgit:git-submodule[1] for more details. |
| 49 | |
| 50 | submodule.<name>.branch:: |
| 51 | A remote branch name for tracking updates in the upstream submodule. |
| 52 | If the option is not specified, it defaults to the remote `HEAD`. |
| 53 | A special value of `.` is used to indicate that the name of the branch |
| 54 | in the submodule should be the same name as the current branch in the |
| 55 | current repository. See the `--remote` documentation in |
| 56 | linkgit:git-submodule[1] for details. |
| 57 | |
| 58 | submodule.<name>.fetchRecurseSubmodules:: |
| 59 | This option can be used to control recursive fetching of this |
| 60 | submodule. If this option is also present in the submodule's entry in |
| 61 | `.git/config` of the superproject, the setting there will override the |
| 62 | one found in `.gitmodules`. |
| 63 | Both settings can be overridden on the command line by using the |
| 64 | `--[no-]recurse-submodules` option to `git fetch` and `git pull`. |
| 65 | |
| 66 | submodule.<name>.ignore:: |
| 67 | Defines under what circumstances `git status` and the diff family show |
| 68 | a submodule as modified. The following values are supported: |
| 69 | + |
| 70 | -- |
| 71 | all;; The submodule will never be considered modified (but will |
| 72 | nonetheless show up in the output of status and commit when it has |
| 73 | been staged). Adding a submodule with `(new commits)` can be |
| 74 | overridden using `git add --force <submodule.path>`. |
| 75 | This setting affects `status`, `update-index`, `diff` and `log` |
| 76 | (due to underlying `diff`). |
| 77 | |
| 78 | dirty;; All changes to the submodule's work tree will be ignored, only |
| 79 | committed differences between the `HEAD` of the submodule and its |
| 80 | recorded state in the superproject are taken into account. |
| 81 | |
| 82 | untracked;; Only untracked files in submodules will be ignored. |
| 83 | Committed differences and modifications to tracked files will show |
| 84 | up. |
| 85 | |
| 86 | none;; No modifications to submodules are ignored, all of committed |
| 87 | differences, and modifications to tracked and untracked files are |
| 88 | shown. This is the default option. |
| 89 | |
| 90 | If this option is also present in the submodule's entry in `.git/config` |
| 91 | of the superproject, the setting there will override the one found in |
| 92 | `.gitmodules`. |
| 93 | |
| 94 | Both settings can be overridden on the command line by using the |
| 95 | `--ignore-submodules` option. The `git submodule` commands are not |
| 96 | affected by this setting. |
| 97 | -- |
| 98 | |
| 99 | submodule.<name>.shallow:: |
| 100 | When set to true, a clone of this submodule will be performed as a |
| 101 | shallow clone (with a history depth of 1) unless the user explicitly |
| 102 | asks for a non-shallow clone. |
| 103 | |
| 104 | NOTES |
| 105 | ----- |
| 106 | |
| 107 | Git does not allow the `.gitmodules` file within a working tree to be a |
| 108 | symbolic link, and will refuse to check out such a tree entry. This |
| 109 | keeps behavior consistent when the file is accessed from the index or a |
| 110 | tree versus from the filesystem, and helps Git reliably enforce security |
| 111 | checks of the file contents. |
| 112 | |
| 113 | EXAMPLES |
| 114 | -------- |
| 115 | |
| 116 | Consider the following `.gitmodules` file: |
| 117 | |
| 118 | ---- |
| 119 | [submodule "libfoo"] |
| 120 | path = include/foo |
| 121 | url = git://foo.com/git/lib.git |
| 122 | |
| 123 | [submodule "libbar"] |
| 124 | path = include/bar |
| 125 | url = git://bar.com/git/lib.git |
| 126 | ---- |
| 127 | |
| 128 | This defines two submodules, `libfoo` and `libbar`. These are expected to |
| 129 | be checked out in the paths `include/foo` and `include/bar`, and for both |
| 130 | submodules a URL is specified which can be used for cloning the submodules. |
| 131 | |
| 132 | SEE ALSO |
| 133 | -------- |
| 134 | linkgit:git-submodule[1], linkgit:gitsubmodules[7], linkgit:git-config[1] |
| 135 | |
| 136 | GIT |
| 137 | --- |
| 138 | Part of the linkgit:git[1] suite |