submod.toml

# 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"
schema_version = "1.1.0"
# Optional metadata: omit it for legacy files, or use exactly "1.0.0" or "1.1.0".
# EXAMPLE ONLY: replace every example.invalid URL with a real repository before
# running init/sync. Parsing this document does not verify that remotes exist.

# ========================= GLOBAL DEFAULTS =========================
# Explicit per-module values override [defaults], then built-in values apply:
# ignore = "none", update = "checkout", fetchRecurse = "on-demand",
# use_git_default_sparse_checkout = false.
# branch has no built-in named branch: Git resolves the remote default.
# Only these five fields are supported globally. Remove a module override with
# `submod change NAME --unset FIELD` to inherit the global value again.
[defaults]
ignore = "dirty"
fetchRecurse = "on-demand"
# branch = "main" # Optional inherited tracking branch; does not advance pins.

# =========================== SUBMODULES ===========================
# Section names are logical identities; new Git registrations use these names.
# A checkout path can differ from its name. Existing Git names are preserved
# when unambiguously resolved. Do not rename an existing entry by adding it again.
# url is required and accepts remote URLs or local repository paths.
# path is relative to the discovered superproject root; omission uses the name.
# Absolute checkout paths, parent traversal and .git components are rejected.
# Commands discover the superproject root even when run from a nested directory.
#
# Per-module fields also include active (default true), shallow (default false),
# and sparse_paths (absent/empty means full checkout). Explicit false overrides
# an inherited sparse-mode true. Unknown fields or conflicting aliases fail.
#
# ignore: all | dirty | untracked | none. Safety checks still protect local work.
# update: checkout | merge | rebase | none. Default update follows the parent
# gitlink; `submod update --remote` explicitly advances to the tracking tip.
# update = "none" skips updating and fetching. Custom !command is rejected.
# fetchRecurse: on-demand | always | never controls Git's recursive fetch policy,
# not whether every command fetches or initializes nested submodules.
# Legacy fetch/fetch_recurse keys and string values "true"/"false" are accepted
# with warnings. Use one spelling per table; write canonical fetchRecurse values.
#
# branch selects an initial/tracking branch. "." follows the superproject branch;
# accepted aliases: current, current-in-super-project, current-in-superproject,
# superproject, super. Use "refs/heads/current" for a literal branch named current.
# Legacy "HEAD" explicitly selects remote-default tracking over a global branch.
#
# Sparse patterns are ordered. With nonempty sparse_paths, submod prepends !/*
# once so only included paths are checked out. use_git_default_sparse_checkout
# = true passes your patterns to Git without that prefix; it does not imply all
# files are included. Sparse checkout limits files, not downloaded objects.
# shallow requests a depth-one new clone; it does not truncate existing history.
#
# active is stored in TOML and local Git config, not .gitmodules. Disabling keeps
# files/history. Delete removes registration/checkout but retains Git history;
# local work may require recovery before removal can proceed.
# Explicit sync reconciles managed URLs, overwriting divergent local URLs.
# Modules not declared here are unmanaged and remain untouched by normal sync.

[vendor-utils]
path = "vendor/utils"
url = "https://example.invalid/utils.git" # Replace before use.
sparse_paths = ["src/", "include/", "*.md"]
ignore = "none"
use_git_default_sparse_checkout = false

[my-submodule]
# path omitted: checkout at my-submodule beneath the superproject root.
url = "https://example.invalid/my-submodule.git" # Replace before use.
active = false # Ineligible for init/sync until explicitly enabled.
shallow = false