1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
# SPDX-FileCopyrightText: 2025 Adam Poulemanos <89049923+bashandbone@users.noreply.github.com>
#
# SPDX-License-Identifier: LicenseRef-PlainMIT OR MIT
#:schema = "https://raw.githubusercontent.com/bashandbone/submod/main/schemas/latest/submod.json"
= "1.1.0"
# =========== Example Submodule Configuration ==========
# ========================= GLOBAL DEFAULTS =========================
# Set global (repo-level) defaults for all submodules here.
# Git does not have global submodule configuration; we resolve the difference and apply the settings to all submodules.
# Defaults (without defining them) are:
# ```toml
# [defaults]
# ignore = "none"
# update = "checkout"
# fetch = "on-demand"
# ```
# Submodule paths can't be set globally, but their default assignment is the submodule name in the repository root.
#
# ## Available options:
# See [docs](https://docs.rs/submod/latest/submod/options/) for details.
# - `ignore`: "all", "dirty", "untracked", "none" [default]
# - `update`: "checkout" [default], "rebase", "merge", "none"
# - `fetch`: "on-demand" [default], "always", "never"
[]
= "dirty" # Override default ignore setting for all submodules
# =========================== SUBMODULE CONFIGURATION ===========================
#
# ## Submodule Name
#
# Each submodule uses its name as the section header.
# If the submodule exists in the repository, use the name from `.gitmodules` or `.git/config`.
#
# ## Available Options
#
# **Submodules support all global options (ignore, fetch, update)**, which will override the defaults. If you want a submodule to maintain default behavior, but set a different global behavior, you *must* explicitly add the options here. Other submodule options are:
#
# ## `url`
# **Required.** The submodule repository URL. Use the same value as in `.gitmodules` or `.git/config`. Accepts remote URLs or local paths (absolute or relative).
#
# ## `path`
# The path where the submodule is checked out. Defaults to the submodule name in the repository root. If not in a repository root, finds the superproject root. Specify a path to override.
#
# ## `branch`
# The submodule branch to check out. Defaults to the submodule's default branch (usually `main` or `master`). You may use `"."` (or aliases: `current`, `current-in-superproject`, `superproject`, `super`) to match the superproject branch. Do not use these as branch names in the submodule repository.
# Submit an issue if you encounter a branch name conflict at https://github.com/bashandbone/submod/issues.
#
# ## `sparse_paths`
# A list of relative paths or glob patterns to include in the sparse checkout. If omitted, includes all files.
# **Deny-all by default:** `submod` automatically prepends `!/*` as the first pattern,
# so _only_ the paths you list are checked out. You declare what you want; everything
# else is excluded. No manual negation rules are needed for the common case.
# Example — check out only `src/`, `include/`, and markdown files at any depth:
# ```toml
# sparse_paths = ["src/", "include/", "*.md"]
# ```
# This writes the following patterns to git's sparse-checkout file:
# ```
# !/* ← deny all by default (added automatically)
# src/ ← include src/
# include/ ← include include/
# *.md ← include markdown files at any depth
# ```
# To match markdown files only at the repository root use `/*.md` instead.
# Any `!/*` entries you add yourself are de-duplicated automatically.
#
# ## `use_git_default_sparse_checkout`
# Set to `true` to opt out of submod's deny-all-by-default model for this submodule
# and use git's standard sparse-checkout semantics instead (no automatic `!/*` prefix).
# Can also be set globally under `[defaults]`.
#
# ## `shallow`
#
# If `true`, performs a shallow clone of the submodule, which means it only fetches the most recent commit. Defaults to `false`. This is useful for large repositories where you only need the latest commit.
#
# NAMES (the part between "[" and "]" below).
# You can name the submodule "bob" or "vendor-utils" if you want in your `submod.toml`
# This name is only used for the configuration, and for your reference when using `submod` commands. You can make the names easy to remember for calling `submod` commands.
# Git expects the submodule name to be the full relative path from the repository root, so that is what we'll use on the back end with `.gitmodules`/`.git/config`.
[]
= "vendor/utils" # <-- will be the name in `.gitmodules` and `.git/config`
= "https://github.com/example/utils.git"
= [
"src/", # All files in src directory
"include/", # All files in include directory
"*.md" # All markdown files at any depth
]
= "all" # Override default ignore setting
[]
= "my-submodule"
= "https://github.com/example/my-submodule.git"
= ["src/", "include/"]
= "all"