Merge pull request #11 from bashandbone/copilot/review-branch-readiness

Fix branch readiness: config loading, dead code removal, sparse checkout, CLI fixes, and documentation

Author: bashandbone

CLI_IMPROVEMENTS_ASSESSMENT_REPORT.md …cs/CLI_IMPROVEMENTS_ASSESSMENT_REPORT.mdCLI_IMPROVEMENTS_ASSESSMENT_REPORT.md renamed to .claudedocs/CLI_IMPROVEMENTS_ASSESSMENT_REPORT.md CLI_IMPROVEMENTS_ASSESSMENT_REPORT.md renamed to .claudedocs/CLI_IMPROVEMENTS_ASSESSMENT_REPORT.md

@@ -143,11 +143,34 @@ branch = "develop"       # track specific branch
 Add a new submodule to your configuration and repository:
 
 ```bash
-submod add my-lib libs/my-lib https://github.com/example/my-lib.git \
+# Basic add
+submod add https://github.com/example/my-lib.git --name my-lib --path libs/my-lib
+
+# With sparse checkout paths and extra options
+submod add https://github.com/example/my-lib.git \
+  --name my-lib \
+  --path libs/my-lib \
   --sparse-paths "src/,include/" \
-  --settings "ignore=all"
+  --branch main \
+  --ignore all \
+  --fetch on-demand
 ```
 
+**Options:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `<URL>` | | *(required)* URL or local path of the submodule repository |
+| `--name` | `-n` | Nickname for the submodule used in your config and commands |
+| `--path` | `-p` | Local directory path where the submodule should be placed |
+| `--branch` | `-b` | Branch to track |
+| `--ignore` | `-i` | Dirty-state ignore level (`all`, `dirty`, `untracked`, `none`) |
+| `--sparse-paths` | `-x` | Comma-separated sparse checkout paths or globs |
+| `--fetch` | `-f` | Recursive fetch behavior (`always`, `on-demand`, `never`) |
+| `--update` | `-u` | Update strategy (`checkout`, `rebase`, `merge`, `none`) |
+| `--shallow` | `-s` | Shallow clone (last commit only) |
+| `--no-init` | | Add to config only; do not clone/initialize |
+
 ### `submod check`
 
 Check the status of all configured submodules:
@@ -180,8 +203,8 @@ Hard reset submodules (stash changes, reset --hard, clean):
 # Reset all submodules
 submod reset --all
 
-# Reset specific submodules
-submod reset my-lib vendor-utils
+# Reset specific submodules (comma-separated)
+submod reset my-lib,vendor-utils
 ```
 
 ### `submod sync`
@@ -192,6 +215,79 @@ Run a complete sync (check + init + update):
 submod sync
 ```
 
+### `submod change`
+
+Change the configuration of an existing submodule:
+
+```bash
+submod change my-lib --branch main --sparse-paths "src/,include/" --fetch always
+```
+
+### `submod change-global`
+
+Change global defaults for all submodules:
+
+```bash
+submod change-global --ignore dirty --update checkout
+```
+
+### `submod list`
+
+List all configured submodules:
+
+```bash
+submod list
+submod list --recursive
+```
+
+### `submod delete`
+
+Delete a submodule from configuration and filesystem:
+
+```bash
+submod delete
+```
+
+### `submod disable`
+
+Disable a submodule without deleting files (sets `active = false`):
+
+```bash
+submod disable
+```
+
+### `submod nuke-it-from-orbit`
+
+Delete all or specific submodules from config and filesystem, with optional reinit:
+
+```bash
+# Nuke all submodules (re-initializes by default)
+submod nuke-it-from-orbit --all
+
+# Nuke specific submodules permanently
+submod nuke-it-from-orbit --kill my-lib,old-dep
+```
+
+### `submod generate-config`
+
+Generate a new configuration file:
+
+```bash
+# From current git submodule setup
+submod generate-config --from-setup .
+
+# As a template with defaults
+submod generate-config --template --output my-config.toml
+```
+
+### `submod completeme`
+
+Generate shell completion scripts:
+
+```bash
+submod completeme bash   # or: zsh, fish, powershell, elvish, nushell
+```
+
 ## 💻 Usage Examples
 
 ### Basic Workflow
@@ -214,7 +310,9 @@ submod sync
 
 ```bash
 # Add a submodule that only checks out specific directories
-submod add react-components src/components https://github.com/company/react-components.git \
+submod add https://github.com/company/react-components.git \
+  --name react-components \
+  --path src/components \
   --sparse-paths "src/Button/,src/Input/,README.md"
 ```
 
@@ -374,9 +472,13 @@ cargo test --test integration_tests  # Integration tests only
 submod/
 ├── src/
 │   ├── main.rs              # CLI entry point
-│   ├── commands.rs          # Command definitions
+│   ├── commands.rs          # Command definitions (clap)
 │   ├── config.rs            # TOML configuration handling
-│   └── git_manager.rs  # Core submodule operations
+│   ├── git_manager.rs       # High-level submodule operations
+│   └── git_ops/             # Git backend abstraction
+│       ├── mod.rs           # GitOpsManager (gix→git2→CLI fallback)
+│       ├── gix_ops.rs       # gitoxide backend
+│       └── git2_ops.rs      # libgit2 backend
 ├── tests/                   # Integration tests
 ├── sample_config/           # Example configurations
 ├── scripts/                 # Development scripts

FEATURE_CODE_REVIEW.md .claudedocs/FEATURE_CODE_REVIEW.mdFEATURE_CODE_REVIEW.md renamed to .claudedocs/FEATURE_CODE_REVIEW.md

@@ -139,7 +139,7 @@ pub enum Commands {
         #[arg(short = 's', long = "shallow", default_value = "false", default_missing_value = "true", help = "If true, sets the submodule as a shallow clone. Set false to disable shallow cloning.")]
         shallow: bool,
 
-        #[arg(short = 'u', long = "url", value_parser = clap::value_parser!(String), help = "Change the URL of the submodule. The submodule name from the url must match an existing submodule.")]
+        #[arg(short = 'U', long = "url", value_parser = clap::value_parser!(String), help = "Change the URL of the submodule. The submodule name from the url must match an existing submodule.")]
         url: Option<String>,
 
         #[arg(long = "active", default_value = "true", value_parser = clap::value_parser!(bool), default_missing_value = "true", help = "If true, the submodule will be considered active and included in operations. If false, will disable the submodule. For a shorter version of this command, use `submod disable <name>` instead.")]

GIT_OPERATIONS_REFACTORING_PLAN.md …edocs/GIT_OPERATIONS_REFACTORING_PLAN.mdGIT_OPERATIONS_REFACTORING_PLAN.md renamed to .claudedocs/GIT_OPERATIONS_REFACTORING_PLAN.md GIT_OPERATIONS_REFACTORING_PLAN.md renamed to .claudedocs/GIT_OPERATIONS_REFACTORING_PLAN.md

@@ -22,7 +22,7 @@ Features:
 
 use std::path::PathBuf;
 use anyhow::Result;
-use serde::{Deserialize, Serialize};
+use serde::{Deserialize, Deserializer, Serialize};
 use std::{collections::HashMap, path::Path};
 use crate::options::{
     ConfigLevel, GitmodulesConvert, SerializableFetchRecurse, SerializableIgnore, SerializableUpdate
@@ -631,12 +631,34 @@ impl From<OtherSubmoduleSettings> for SubmoduleEntry {
 /// A collection of submodule entries, including sparse checkouts
 ///
 /// Revamped to better reflect git's structure so we can use the SubmoduleEntry types directly with gix/git2
-#[derive(Debug, Default, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[derive(Debug, Default, Clone, Serialize, PartialEq, Eq)]
 pub struct SubmoduleEntries {
     submodules: Option<HashMap<SubmoduleName, SubmoduleEntry>>,
     sparse_checkouts: Option<HashMap<SubmoduleName, Vec<String>>>,
 }
 
+impl<'de> Deserialize<'de> for SubmoduleEntries {
+    /// Deserialize from the flat TOML format where each top-level key is a submodule name.
+    /// Accepts a map where each key maps to a [`SubmoduleEntry`], building both the
+    /// `submodules` map and the `sparse_checkouts` map from each entry's `sparse_paths`.
+    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let map: HashMap<SubmoduleName, SubmoduleEntry> =
+            HashMap::deserialize(deserializer)?;
+        let mut sparse_checkouts: HashMap<SubmoduleName, Vec<String>> = HashMap::new();
+        for (name, entry) in &map {
+            if let Some(paths) = &entry.sparse_paths {
+                if !paths.is_empty() {
+                    sparse_checkouts.insert(name.clone(), paths.clone());
+                }
+            }
+        }
+        Ok(SubmoduleEntries {
+            submodules: Some(map),
+            sparse_checkouts: Some(sparse_checkouts),
+        })
+    }
+}
+
 impl SubmoduleEntries {
     /// Create a new empty SubmoduleEntries
     pub fn new(submodules: Option<HashMap<SubmoduleName, SubmoduleEntry>>, sparse_checkouts: Option<HashMap<SubmoduleName, Vec<String>>>) -> Self {
@@ -928,12 +950,13 @@ impl Config {
 
     /// Load configuration from a file, merging with CLI options
     pub fn load(&self, path: impl AsRef<Path>, cli_options: Config) -> anyhow::Result<Self> {
-        let fig = Figment::from(Self::default()) // 1) start from Rust-side defaults
-        .merge(Toml::file(path).nested())  // 2) file-based overrides
-        .merge(cli_options);      // 3) CLI overrides file
-
-        // 4) extract into Config, then post-process submodules
-        let cfg: Config = fig.extract()?;
+        let cfg: Config = Figment::new()
+            .merge(Toml::file(path))
+            // Merge only the defaults sub-field from CLI options so that the flat submodule
+            // entries (written as top-level TOML sections) are not corrupted by the
+            // SubmoduleEntries serialized field names ("submodules", "sparse_checkouts").
+            .merge(figment::providers::Serialized::defaults(cli_options.defaults).key("defaults"))
+            .extract()?;
         Ok(cfg.apply_defaults())
     }
 
@@ -943,10 +966,9 @@ impl Config {
             Some(ref p) => p,
             None => &".",
         };
-        let fig = Figment::from(Self::default())
-            .merge(Toml::file(p).nested());
-        // Extract the configuration from Figment
-        let cfg: Config = fig.extract()?;
+        let cfg: Config = Figment::new()
+            .merge(Toml::file(p))
+            .extract()?;
         Ok(cfg.apply_defaults())
     }