chore(schemas): Update config schemas to reflect new sparse path handling and the use_git_default_sparse_checkout setting

Author: bashandbone

schemas/submod.json

@@ -0,0 +1 @@
+schemas/v1.1.0/submod_config_v1.1.0.json

schemas/v1.0.0/submod_config_v1.0.0.json

@@ -16,7 +16,8 @@
       "properties": {
         "ignore": { "$ref": "#/$defs/ignoreValue" },
         "update": { "$ref": "#/$defs/updateValue" },
-        "fetch":  { "$ref": "#/$defs/fetchValue" }
+        "fetch":  { "$ref": "#/$defs/fetchValue" },
+        "use_git_default_sparse_checkout": { "$ref": "#/$defs/useGitDefaultSparseCheckoutValue" }
       },
       "additionalProperties": false
     }
@@ -43,6 +44,11 @@
       "default": "on-demand",
       "description": "When to fetch submodule updates from the remote.\n- \"on-demand\": fetch only when needed (default)\n- \"always\": fetch on every operation\n- \"never\": never fetch automatically\nhttps://docs.rs/submod/latest/submod/options/"
     },
+    "useGitDefaultSparseCheckoutValue": {
+      "type": "boolean",
+      "default": false,
+      "description": "If true, uses git's default sparse checkout behavior for the submodule. This means all files are included by default, and any specified sparse_paths are added to the checkout rather than replacing it. If false (the default), specifying sparse_paths replaces the default behavior and only the specified paths are included. We think our approach is more intuitive, but this option allows you to opt in to git's behavior if you prefer it or need it for compatibility reasons."
+    },
     "submodule": {
       "type": "object",
       "description": "Configuration for a single submodule. The section name is your local alias for the submodule; submod maps it to the full relative path in .gitmodules and .git/config.",
@@ -63,7 +69,7 @@
         "sparse_paths": {
           "type": "array",
           "items": { "type": "string" },
-          "description": "Relative paths or glob patterns to include in a sparse checkout. If omitted, all files are checked out.\nWhen set, git prepends:\n  /*\n  !/*/\nThis includes only root-level files by default. To include subdirectories, add paths like \"src/\". To exclude root files, prefix with \"!\" (e.g., \"!/README.md\")."
+          "description": "Relative paths or glob patterns to include in a sparse checkout. By default, **no** paths are included when sparse_paths -- only those explicitly listed will be included. This is different from git's default sparse checkout behavior, which includes all files by default and adds specified paths to the checkout. We think our approach is more intuitive, but if you prefer git's behavior or need it for compatibility reasons, you can set use_git_default_sparse_checkout to true globally or for this submodule to have specified paths added to the default checkout rather than replacing it."
         },
         "shallow": {
           "type": "boolean",
@@ -72,7 +78,8 @@
         },
         "ignore": { "$ref": "#/$defs/ignoreValue" },
         "update": { "$ref": "#/$defs/updateValue" },
-        "fetch":  { "$ref": "#/$defs/fetchValue" }
+        "fetch":  { "$ref": "#/$defs/fetchValue" },
+        "use_git_default_sparse_checkout": { "$ref": "#/$defs/useGitDefaultSparseCheckoutValue" }
       },
       "additionalProperties": false
     }

schemas/v1.1.0/submod_config_v1.1.0.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/bashandbone/submod/main/schemas/submod.json",
+  "title": "submod configuration",
+  "description": "Configuration file for submod, a git submodule management CLI.\nhttps://docs.rs/",
+  "type": "object",
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^v?\\d+(\\.\\d+){0,2}$",
+      "description": "The version of the submod configuration schema in use. Accepts \"1\", \"1.0\", or \"1.0.0\" format.\nhttps://docs.rs/submod"
+    },
+    "defaults": {
+      "type": "object",
+      "description": "Global defaults applied to all submodules. Git has no native global submodule configuration; submod resolves this by applying these settings across all submodule entries. Any settings you set for an individual submodule will override these defaults.\nhttps://docs.rs/submod/latest/submod/options/",
+      "properties": {
+        "ignore": { "$ref": "#/$defs/ignoreValue" },
+        "update": { "$ref": "#/$defs/updateValue" },
+        "fetch":  { "$ref": "#/$defs/fetchValue" },
+        ""
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": {
+    "$ref": "#/$defs/submodule"
+  },
+  "$defs": {
+    "ignoreValue": {
+      "type": "string",
+      "enum": ["all", "dirty", "untracked", "none"],
+      "default": "none",
+      "description": "Controls which changes cause a submodule to appear as modified in git status.\n- \"none\": report all changes (default)\n- \"untracked\": ignore untracked files\n- \"dirty\": ignore all working tree changes, only track commits\n- \"all\": always ignore the submodule\nhttps://docs.rs/submod/latest/submod/options/"
+    },
+    "updateValue": {
+      "type": "string",
+      "enum": ["checkout", "rebase", "merge", "none"],
+      "default": "checkout",
+      "description": "How to update the submodule when the superproject moves to a new commit.\n- \"checkout\": detach HEAD at the recorded commit (default)\n- \"rebase\": rebase current branch onto the recorded commit\n- \"merge\": merge the recorded commit into the current branch\n- \"none\": do not update\nhttps://docs.rs/submod/latest/submod/options/"
+    },
+    "fetchValue": {
+      "type": "string",
+      "enum": ["on-demand", "always", "never"],
+      "default": "on-demand",
+      "description": "When to fetch submodule updates from the remote.\n- \"on-demand\": fetch only when needed (default)\n- \"always\": fetch on every operation\n- \"never\": never fetch automatically\nhttps://docs.rs/submod/latest/submod/options/"
+    },
+    "submodule": {
+      "type": "object",
+      "description": "Configuration for a single submodule. The section name is your local alias for the submodule; submod maps it to the full relative path in .gitmodules and .git/config.",
+      "required": ["url"],
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "Required. The submodule repository URL. Accepts remote URLs (https, ssh) or local paths (absolute or relative). Use the same value as in .gitmodules or .git/config."
+        },
+        "path": {
+          "type": "string",
+          "description": "Path where the submodule is checked out, relative to the superproject root. Defaults to the submodule name in the repository root."
+        },
+        "branch": {
+          "type": "string",
+          "description": "Branch to track in the submodule. Defaults to the submodule's default branch (usually main or master).\nUse \".\" or the aliases \"current\", \"current-in-superproject\", \"superproject\", or \"super\" to track the superproject's current branch. **Do not use these strings as actual branch names in the submodule repository.** If you need to track a branch with one of these names, use the full branch name (e.g., \"refs/heads/current\")."
+        },
+        "sparse_paths": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Relative paths or glob patterns to include in a sparse checkout. If omitted, all files are checked out.\nWhen set, git prepends:\n  /*\n  !/*/\nThis includes only root-level files by default. To include subdirectories, add paths like \"src/\". To exclude root files, prefix with \"!\" (e.g., \"!/README.md\")."
+        },
+        "shallow": {
+          "type": "boolean",
+          "default": false,
+          "description": "If true, performs a shallow clone (only the most recent commit). Useful for large repositories where full history is not needed."
+        },
+        "ignore": { "$ref": "#/$defs/ignoreValue" },
+        "update": { "$ref": "#/$defs/updateValue" },
+        "fetch":  { "$ref": "#/$defs/fetchValue" }
+      },
+      "additionalProperties": false
+    }
+  }
+}