@openvcs/git-plugin 0.1.0-beta.2 → 0.1.0-edge.20260422.23

package/ARCHITECTURE.md

@@ -23,12 +23,20 @@ through `@openvcs/sdk/runtime` delegates and exposes a single VCS backend id:
   exact `vcs.*` JSON-RPC method names consumed by the runtime.
 - Status reads use `git status --porcelain=1 --branch -z -uall` so file paths are
   NUL-delimited and not C-quoted.
+- After porcelain parsing, the plugin cross-references `.gitmodules` paths so
+  tracked submodule entries are surfaced with a dedicated submodule status marker
+  for the client UI.
 - For rename and copy records, the porcelain format includes two NUL-terminated
   paths: the original/source path first, then the new/destination path. The
   plugin assigns `path` to the new path and `old_path` to the original path.
 - Network commands (`fetch`, `push`, `pull`) omit optional arguments (remote,
   refspec, branch) when not provided, allowing Git to use its defaults instead
   of receiving empty string arguments.
+- Clone uses `git clone --recurse-submodules` so repositories arrive with
+  submodules initialized by default.
+- The Repository menu submodule toolkit keeps pinned `git submodule update`
+  behavior separate from explicit `--remote` updates that follow the configured
+  branch in `.gitmodules`.
 
 ## State
 

package/README.md

@@ -9,6 +9,9 @@ This directory contains the System Git VCS backend plugin used by OpenVCS.
 - The plugin can add top-level app menus and items through `@openvcs/sdk/runtime` helpers.
 - The plugin can open generic plugin-owned modals with the SDK `ModalBuilder` helper.
 - The Repository menu includes Git-only submodule management tooling.
+- In the desktop client, the `Submodules` entry appears in `Repository` after a Git repository is open and the Git plugin runtime is active.
+- Repository clone operations recurse into submodules by default.
+- Repository status views tag tracked submodule paths distinctly so the client can render them as submodules.
 - Git operations are executed through the local `git` CLI.
 - The runtime uses a trust model (no per-capability permission prompts).
 
@@ -18,7 +21,7 @@ This directory contains the System Git VCS backend plugin used by OpenVCS.
 npm install
 ```
 
-- The SDK dependency is pinned to the `^0.2` range so it tracks the latest `0.2.x` releases.
+- The SDK dependency tracks the `edge` tag so it always follows the latest SDK commit.
 
 ## Validate
 
@@ -41,6 +44,12 @@ npm run build
 npm test
 ```
 
+Submodule workflow highlights:
+
+- `clone_repo` uses `git clone --recurse-submodules`.
+- Repository > Submodules supports add, sync, remove, pinned updates, and explicit remote-tracking updates.
+- `Update Remote` follows the branch configured for each submodule in `.gitmodules`.
+
 ## Pack For Config Use
 
 ```bash
@@ -56,11 +65,13 @@ The npm package can be consumed from prerelease channels published by CI:
 
 - `latest`: stable releases
 - `beta`: builds from the `Beta` branch
+- `edge`: working builds from `Dev` push commits
 - `nightly`: scheduled builds from `Dev` when there are changes since the last nightly
 
 Examples:
 
 ```bash
+npm install @openvcs/git-plugin@edge
 npm install @openvcs/git-plugin@beta
 npm install @openvcs/git-plugin@nightly
 ```

package/bin/git.js

@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process';
 import { rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { pluginError } from '@openvcs/sdk/runtime';
-import { asString, buildFetchArgs, buildPullFfOnlyArgs, buildPushArgs, parseCommits, parseStatusOutput, } from './plugin-helpers.js';
+import { applySubmoduleStatusHints, asString, buildFetchArgs, buildPullFfOnlyArgs, buildPushArgs, buildSubmoduleUpdateArgs, parseCommits, parseStatusOutput, } from './plugin-helpers.js';
 export class GitCommand {
     cwd;
     constructor(cwd) {
@@ -60,7 +60,7 @@ export class GitCommand {
     }
     status() {
         const result = this.run(['status', '--porcelain=1', '--branch', '-z', '-uall']);
-        const parsed = parseStatusOutput(result.stdout);
+        const parsed = applySubmoduleStatusHints(parseStatusOutput(result.stdout), this.listSubmodulePaths());
         return { ...parsed, exitCode: result.status };
     }
     currentBranch() {
@@ -163,26 +163,41 @@ export class GitCommand {
         const args = buildPullFfOnlyArgs(options);
         return this.runChecked(args, 'git-pull-failed');
     }
-    commit(message) {
-        return this.runChecked(['commit', '-m', message], 'git-commit-failed');
+    /** Returns the current HEAD commit id. */
+    currentHead() {
+        return this.runChecked(['rev-parse', 'HEAD'], 'git-head-failed').stdout.trim();
     }
-    commitIndex(message, name, email, paths) {
-        const args = ['commit'];
-        if (paths && paths.length > 0) {
-            args.push('--', ...paths);
-        }
-        else {
-            args.push('-a');
-        }
+    /** Creates a commit, optionally limited to the provided paths. */
+    commit(message, name, email, paths) {
+        const execArgs = [
+            ...(name ? ['-c', `user.name=${name}`] : []),
+            ...(email ? ['-c', `user.email=${email}`] : []),
+            'commit',
+            '-m',
+            message,
+            ...(paths && paths.length > 0 ? ['--', ...paths] : []),
+        ];
+        return this.runChecked(execArgs, 'git-commit-failed');
+    }
+    /** Creates a commit from the current index only. */
+    commitIndex(message, name, email) {
         const commitMessage = message || 'Stage changes';
         const execArgs = [
             ...(name ? ['-c', `user.name=${name}`] : []),
             ...(email ? ['-c', `user.email=${email}`] : []),
-            ...args,
-            '-m', commitMessage,
+            'commit',
+            '-m',
+            commitMessage,
         ];
         return this.runChecked(execArgs, 'git-commit-failed');
     }
+    /** Stages the provided repository-relative paths into the index. */
+    stagePaths(paths) {
+        if (paths.length === 0) {
+            return;
+        }
+        this.runChecked(['add', '-A', '--', ...paths], 'git-stage-paths-failed');
+    }
     listCommits(options = {}) {
         const args = ['log', '--all'];
         if (options.topo_order) {
@@ -206,7 +221,7 @@ export class GitCommand {
         if (options.until_utc) {
             args.push(`--until=${options.until_utc}`);
         }
-        args.push('--pretty=format:%H%f%x00%aN%x00%aI%x00%P%x1e');
+        args.push('--pretty=format:%H%x00%s%x00%aN%x00%aI%x00%P%x1e');
         if (options.branch) {
             args.push(options.branch);
         }
@@ -217,9 +232,10 @@ export class GitCommand {
         const commits = parseCommits(result.stdout);
         return { commits, exitCode: result.status };
     }
-    listSubmodules() {
+    /** Reads `.gitmodules` entries indexed by submodule name and path. */
+    readSubmoduleConfig() {
         const configResult = this.run(['config', '-f', '.gitmodules', '--null', '--list']);
-        const configByName = new Map();
+        const byName = new Map();
         if (configResult.status === 0) {
             for (const entry of configResult.stdout.split('\0')) {
                 const trimmed = entry.trim();
@@ -234,22 +250,30 @@ export class GitCommand {
                 if (!match)
                     continue;
                 const [, name, field] = match;
-                const target = configByName.get(name) || { name };
+                const target = byName.get(name) || { name };
                 if (field === 'path')
                     target.path = value;
                 if (field === 'url')
                     target.url = value;
                 if (field === 'branch')
                     target.branch = value;
-                configByName.set(name, target);
+                byName.set(name, target);
             }
         }
-        const configByPath = new Map();
-        for (const entry of configByName.values()) {
+        const byPath = new Map();
+        for (const entry of byName.values()) {
             if (entry.path) {
-                configByPath.set(entry.path, entry);
+                byPath.set(entry.path, entry);
             }
         }
+        return { byName, byPath };
+    }
+    /** Returns known submodule paths from `.gitmodules`. */
+    listSubmodulePaths() {
+        return new Set(this.readSubmoduleConfig().byPath.keys());
+    }
+    listSubmodules() {
+        const { byPath: configByPath } = this.readSubmoduleConfig();
         const statusResult = this.run(['submodule', 'status', '--recursive']);
         if (statusResult.status !== 0) {
             return [];
@@ -295,10 +319,18 @@ export class GitCommand {
         return this.runChecked(args, 'git-submodule-add-failed');
     }
     updateSubmodule(path) {
-        return this.runChecked(['submodule', 'update', '--init', '--recursive', '--', path], 'git-submodule-update-failed');
+        return this.runChecked(buildSubmoduleUpdateArgs({ path }), 'git-submodule-update-failed');
     }
     updateAllSubmodules() {
-        return this.runChecked(['submodule', 'update', '--init', '--recursive'], 'git-submodule-update-failed');
+        return this.runChecked(buildSubmoduleUpdateArgs({}), 'git-submodule-update-failed');
+    }
+    /** Updates one submodule from its configured branch recursively. */
+    updateSubmoduleRemote(path) {
+        return this.runChecked(buildSubmoduleUpdateArgs({ path, remote: true }), 'git-submodule-update-remote-failed');
+    }
+    /** Updates all submodules from their configured branches recursively. */
+    updateAllSubmodulesRemote() {
+        return this.runChecked(buildSubmoduleUpdateArgs({ remote: true }), 'git-submodule-update-remote-failed');
     }
     syncSubmodule(path) {
         return this.runChecked(['submodule', 'sync', '--recursive', '--', path], 'git-submodule-sync-failed');
@@ -354,8 +386,11 @@ export class GitCommand {
     hashObject(content) {
         return this.run(['hash-object', '-w', '--stdin'], { stdin: content }).stdout.trim();
     }
+    /** Stages a textual patch into the index without requiring worktree/index parity. */
     stagePatch(patch) {
-        this.runChecked(['apply', '--3way', '--index'], 'git-stage-patch-failed', { stdin: patch });
+        this.runChecked(['apply', '--cached', '--unidiff-zero'], 'git-stage-patch-failed', {
+            stdin: patch,
+        });
     }
     applyReversePatch(patch) {
         this.runChecked(['apply', '-R', patch], 'git-apply-reverse-failed');

package/bin/plugin-helpers.js

@@ -52,6 +52,13 @@ export function buildPushArgs(params) {
     pushOptionalArg(args, params.refspec);
     return args;
 }
+/** Builds `git clone` arguments with recursive submodule initialization enabled. */
+export function buildCloneArgs(params) {
+    const args = ['clone', '--recurse-submodules'];
+    pushOptionalArg(args, params.url);
+    pushOptionalArg(args, params.dest);
+    return args;
+}
 /** Builds `git pull --ff-only` arguments while omitting empty optional values. */
 export function buildPullFfOnlyArgs(params) {
     const args = ['pull', '--ff-only'];
@@ -59,6 +66,18 @@ export function buildPullFfOnlyArgs(params) {
     pushOptionalArg(args, params.branch);
     return args;
 }
+/** Builds `git submodule update` arguments for pinned or remote-tracking updates. */
+export function buildSubmoduleUpdateArgs(params) {
+    const args = ['submodule', 'update', '--init', '--recursive'];
+    if (params.remote === true) {
+        args.push('--remote');
+    }
+    const path = asTrimmedString(params.path);
+    if (path) {
+        args.push('--', path);
+    }
+    return args;
+}
 /** Parses `git status --porcelain=1 --branch -z -uall` output into OpenVCS payloads. */
 export function parseStatusOutput(output) {
     const records = output.split('\0').filter(Boolean);
@@ -130,6 +149,31 @@ export function parseStatusOutput(output) {
         },
     };
 }
+/** Applies submodule-specific status labels to known submodule paths. */
+export function applySubmoduleStatusHints(parsed, submodulePaths) {
+    const knownPaths = new Set(Array.from(submodulePaths)
+        .map((entry) => asTrimmedString(entry))
+        .filter(Boolean));
+    if (knownPaths.size === 0) {
+        return parsed;
+    }
+    return {
+        ...parsed,
+        payload: {
+            ...parsed.payload,
+            files: parsed.payload.files.map((file) => {
+                const path = asTrimmedString(file.path);
+                if (!knownPaths.has(path)) {
+                    return file;
+                }
+                return {
+                    ...file,
+                    status: 'S',
+                };
+            }),
+        },
+    };
+}
 /** Parses `git log` output into commit entries expected by the host. */
 export function parseCommits(raw) {
     const records = raw

package/bin/plugin-request-handler.js

@@ -1,8 +1,63 @@
 // Copyright © 2025-2026 OpenVCS Contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 import { VcsDelegateBase, pluginError, } from '@openvcs/sdk/runtime';
-import { asNumber, asRecord, asString, asStringArray, asTrimmedString, } from './plugin-helpers.js';
+import { asNumber, asRecord, asString, asStringArray, asTrimmedString, buildCloneArgs, parseStatusOutput, } from './plugin-helpers.js';
 import { GitCommand } from './git.js';
+/** Reduces a file status string to the primary status code needed for discard routing. */
+function getPrimaryDiscardStatus(status) {
+    const normalized = asTrimmedString(status);
+    if (!normalized) {
+        return 'M';
+    }
+    for (const candidate of ['?', 'R', 'C', 'A', 'D', 'U', 'T', 'S', 'M']) {
+        if (normalized.includes(candidate)) {
+            return candidate;
+        }
+    }
+    return normalized[0] ?? 'M';
+}
+/** Builds a discard plan that handles tracked, added, copied, and renamed paths. */
+export function planDiscardPaths(statusOutput) {
+    const restore = new Set();
+    const unstageThenRemove = new Set();
+    const clean = new Set();
+    const parsed = parseStatusOutput(statusOutput);
+    for (const file of parsed.payload.files) {
+        const path = asTrimmedString(file.path);
+        const oldPath = asTrimmedString(file.old_path);
+        const primaryStatus = getPrimaryDiscardStatus(file.status);
+        if (!path) {
+            continue;
+        }
+        if (primaryStatus === '?') {
+            clean.add(path);
+            continue;
+        }
+        if (primaryStatus === 'R') {
+            if (oldPath) {
+                restore.add(oldPath);
+            }
+            if (file.staged) {
+                unstageThenRemove.add(path);
+            }
+            clean.add(path);
+            continue;
+        }
+        if (primaryStatus === 'C' || primaryStatus === 'A') {
+            if (file.staged) {
+                unstageThenRemove.add(path);
+            }
+            clean.add(path);
+            continue;
+        }
+        restore.add(path);
+    }
+    return {
+        restore: Array.from(restore),
+        unstageThenRemove: Array.from(unstageThenRemove),
+        clean: Array.from(clean),
+    };
+}
 /** Implements the Git-backed `vcs.*` delegate surface for the SDK runtime. */
 export class GitVcsDelegates extends VcsDelegateBase {
     /** Returns the required repository worktree path for a session id. */
@@ -45,7 +100,7 @@ export class GitVcsDelegates extends VcsDelegateBase {
             throw pluginError('vcs-clone-invalid-args', 'url and dest are required');
         }
         const git = this.deps.createGitCommand(process.cwd());
-        const output = git.runChecked(['clone', url, destination], 'vcs-clone-failed');
+        const output = git.runChecked(buildCloneArgs({ url, dest: destination }), 'vcs-clone-failed');
         const lines = `${output.stdout}\n${output.stderr}`
             .split(/\r?\n/g)
             .map((line) => line.trim())
@@ -159,15 +214,13 @@ export class GitVcsDelegates extends VcsDelegateBase {
     }
     commit(params, _context) {
         const git = this.requireGit(params.session_id);
-        const result = git.runChecked(['rev-parse', 'HEAD'], 'git-commit-failed');
-        git.commit(asTrimmedString(params.message));
-        return result.stdout.trim();
+        git.commit(asTrimmedString(params.message), asTrimmedString(params.name), asTrimmedString(params.email), asStringArray(params.paths));
+        return git.currentHead();
     }
     commitIndex(params, _context) {
         const git = this.requireGit(params.session_id);
-        const result = git.runChecked(['rev-parse', 'HEAD'], 'git-commit-failed');
-        git.commitIndex(asTrimmedString(params.message), asTrimmedString(params.name), asTrimmedString(params.email), asStringArray(params.paths));
-        return result.stdout.trim();
+        git.commitIndex(asTrimmedString(params.message), asTrimmedString(params.name), asTrimmedString(params.email));
+        return git.currentHead();
     }
     getStatusSummary(params, _context) {
         const git = this.requireGit(params.session_id);
@@ -225,13 +278,28 @@ export class GitVcsDelegates extends VcsDelegateBase {
         git.stagePatch(asString(params.patch));
         return null;
     }
+    stagePaths(params, _context) {
+        const git = this.requireGit(params.session_id);
+        git.stagePaths(asStringArray(params.paths));
+        return null;
+    }
     discardPaths(params, _context) {
         const git = this.requireGit(params.session_id);
         const paths = asStringArray(params.paths);
         if (paths.length === 0) {
             return null;
         }
-        git.runChecked(['checkout', '--', ...paths], 'git-discard-paths-failed');
+        const status = git.runChecked(['status', '--porcelain=1', '-z', '-uall', '--', ...paths], 'git-discard-paths-failed');
+        const discardPlan = planDiscardPaths(status.stdout);
+        if (discardPlan.unstageThenRemove.length > 0) {
+            git.runChecked(['rm', '-f', '--cached', '--', ...discardPlan.unstageThenRemove], 'git-discard-paths-failed');
+        }
+        if (discardPlan.restore.length > 0) {
+            git.runChecked(['restore', '--source=HEAD', '--staged', '--worktree', '--', ...discardPlan.restore], 'git-discard-paths-failed');
+        }
+        if (discardPlan.clean.length > 0) {
+            git.runChecked(['clean', '-f', '--', ...discardPlan.clean], 'git-discard-paths-failed');
+        }
         return null;
     }
     applyReversePatch(params, _context) {

package/bin/plugin.js

@@ -38,7 +38,7 @@ export function OnPluginStart() {
     }
     const delegates = new GitVcsDelegates(createGitRuntimeDependencies());
     PluginDefinition.vcs = delegates.toDelegates();
-    const repoMenu = getOrCreateMenu('repository', 'Repository');
+    const repoMenu = getOrCreateMenu('repository', 'Repository', { surface: 'menubar' });
     if (repoMenu) {
         repoMenu.addItem({ label: 'Edit .gitignore', action: 'repo-edit-gitignore' });
         repoMenu.addItem({ label: 'Edit .gitattributes', action: 'repo-edit-gitattributes' });

package/bin/submodules.js

@@ -34,6 +34,12 @@ function buildSubmoduleRow(entry) {
         description,
         actions: [
             { type: 'button', id: 'submodules-update', content: 'Update', payload: { path: entry.path } },
+            {
+                type: 'button',
+                id: 'submodules-update-remote',
+                content: 'Update Remote',
+                payload: { path: entry.path },
+            },
             { type: 'button', id: 'submodules-sync', content: 'Sync', payload: { path: entry.path } },
             {
                 type: 'button',
@@ -52,33 +58,51 @@ async function openSubmodulesModal() {
     console.log('Git submodules: building modal', { count: entries.length });
     const modal = new ModalBuilder('Manage Submodules')
         .text('Review, add, update, sync, and remove submodules without leaving Git.')
+        .text('Use Update Remote to follow each submodule branch configured in .gitmodules.')
         .separator()
-        .input('url', 'Submodule URL', {
-        kind: 'url',
-        placeholder: 'https://example.com/repo.git',
-    })
-        .input('path', 'Submodule Path', {
-        placeholder: 'libs/example',
-    })
-        .input('name', 'Submodule Name', {
-        placeholder: 'example',
-    })
-        .input('branch', 'Branch (optional)', {
-        placeholder: 'main',
-    })
-        .button('submodules-add', 'Add Submodule', {
-        variant: 'primary',
-        align: 'centered',
-    })
-        .button('repo-submodules', 'Refresh', {
-        align: 'centered',
-    })
-        .button('submodules-update-all', 'Update All (Recursive)', {
-        align: 'centered',
-    })
-        .button('submodules-sync-all', 'Sync All', {
-        align: 'centered',
-    })
+        .verticalBox([
+        {
+            type: 'input',
+            id: 'url',
+            label: 'Submodule URL',
+            kind: 'url',
+            placeholder: 'https://example.com/repo.git',
+        },
+        {
+            type: 'grid',
+            columns: 'minmax(0, 1fr) minmax(0, 1fr)',
+            gap: '.75rem',
+            content: [
+                {
+                    type: 'input',
+                    id: 'path',
+                    label: 'Submodule Path',
+                    placeholder: 'libs/example',
+                },
+                {
+                    type: 'input',
+                    id: 'name',
+                    label: 'Submodule Name',
+                    placeholder: 'example',
+                },
+            ],
+        },
+        {
+            type: 'input',
+            id: 'branch',
+            label: 'Branch (optional)',
+            placeholder: 'main',
+        },
+    ], { gap: '1rem' })
+        .horizontalBox([
+        { type: 'button', id: 'submodules-add', content: 'Add Submodule', variant: 'primary' },
+        { type: 'button', id: 'repo-submodules', content: 'Refresh' },
+    ], { gap: '.5rem', align: 'centered', wrap: true })
+        .horizontalBox([
+        { type: 'button', id: 'submodules-update-all', content: 'Update All (Recursive)' },
+        { type: 'button', id: 'submodules-update-all-remote', content: 'Update All From Branches' },
+        { type: 'button', id: 'submodules-sync-all', content: 'Sync All' },
+    ], { gap: '.5rem', align: 'centered', wrap: true })
         .separator()
         .list('submodules', {
         label: 'Submodules',
@@ -95,14 +119,16 @@ async function openRemoveConfirmationModal(path, name) {
     console.log('Git submodules: building remove confirmation', { path: submodulePath, name });
     const modal = new ModalBuilder('Confirm Submodule Removal')
         .text(`Remove the submodule at ${submodulePath}? This will deinitialize the submodule, remove it from the index, and delete its working tree entry.`)
-        .button('repo-submodules', 'Back', {
-        align: 'centered',
-    })
-        .button('submodules-remove-confirm', 'Remove Submodule', {
-        variant: 'danger',
-        align: 'centered',
-        payload: { path: submodulePath, name: String(name || '').trim() || undefined },
-    });
+        .horizontalBox([
+        { type: 'button', id: 'repo-submodules', content: 'Back' },
+        {
+            type: 'button',
+            id: 'submodules-remove-confirm',
+            content: 'Remove Submodule',
+            variant: 'danger',
+            payload: { path: submodulePath, name: String(name || '').trim() || undefined },
+        },
+    ], { gap: '.5rem', align: 'centered', wrap: true });
     return modal.open();
 }
 /** Removes one submodule and refreshes the toolkit modal. */
@@ -136,6 +162,15 @@ async function updateSubmodule(payload) {
     git.updateSubmodule(path);
     await openSubmodulesModal();
 }
+/** Updates one submodule from its configured branch and refreshes the toolkit modal. */
+async function updateSubmoduleRemote(payload) {
+    const path = payloadString(payload, 'path');
+    if (!path)
+        return;
+    const git = createGitCommand();
+    git.updateSubmoduleRemote(path);
+    await openSubmodulesModal();
+}
 /** Syncs one submodule and refreshes the toolkit modal. */
 async function syncSubmodule(payload) {
     const path = payloadString(payload, 'path');
@@ -151,6 +186,12 @@ async function updateAllSubmodules() {
     git.updateAllSubmodules();
     await openSubmodulesModal();
 }
+/** Updates all submodules from their configured branches and refreshes the toolkit modal. */
+async function updateAllSubmodulesRemote() {
+    const git = createGitCommand();
+    git.updateAllSubmodulesRemote();
+    await openSubmodulesModal();
+}
 /** Syncs all submodules recursively and refreshes the toolkit modal. */
 async function syncAllSubmodules() {
     const git = createGitCommand();
@@ -159,7 +200,7 @@ async function syncAllSubmodules() {
 }
 /** Registers the Git submodule toolkit menu and action handlers. */
 export function registerSubmoduleToolkit() {
-    const repoMenu = getOrCreateMenu('repository', 'Repository');
+    const repoMenu = getOrCreateMenu('repository', 'Repository', { surface: 'menubar' });
     repoMenu?.addItem({ label: 'Submodules', action: 'repo-submodules' });
     registerAction('repo-submodules', async () => {
         console.log('Git submodules: repo-submodules action invoked');
@@ -171,12 +212,18 @@ export function registerSubmoduleToolkit() {
     registerAction('submodules-update-all', async () => {
         return updateAllSubmodules();
     });
+    registerAction('submodules-update-all-remote', async () => {
+        return updateAllSubmodulesRemote();
+    });
     registerAction('submodules-sync-all', async () => {
         return syncAllSubmodules();
     });
     registerAction('submodules-update', async (payload) => {
         return updateSubmodule(asPayload(payload));
     });
+    registerAction('submodules-update-remote', async (payload) => {
+        return updateSubmoduleRemote(asPayload(payload));
+    });
     registerAction('submodules-sync', async (payload) => {
         return syncSubmodule(asPayload(payload));
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/git-plugin",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-edge.20260422.23",
   "description": "OpenVCS Git plugin - Node.js runtime",
   "license": "GPL-3.0-or-later",
   "homepage": "https://github.com/Open-VCS/OpenVCS-Plugin-Git",
@@ -18,7 +18,7 @@
   "openvcs": {
     "id": "openvcs.git",
     "name": "Git",
-    "version": "0.1.0-beta.2",
+    "version": "0.1.0-edge.20260422.23",
     "author": "OpenVCS Contributors",
     "description": "Git VCS backend plugin for OpenVCS",
     "default_enabled": true,
@@ -37,7 +37,7 @@
     "build": "node ./node_modules/@openvcs/sdk/bin/openvcs.js build"
   },
   "dependencies": {
-    "@openvcs/sdk": "^0.2.16"
+    "@openvcs/sdk": "edge"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",

package/src/git.ts

@@ -14,10 +14,12 @@ import type {
 } from '@openvcs/sdk/types';
 import type { GitCommandResult, RunGitOptions } from './plugin-types.js';
 import {
+  applySubmoduleStatusHints,
   asString,
   buildFetchArgs,
   buildPullFfOnlyArgs,
   buildPushArgs,
+  buildSubmoduleUpdateArgs,
   parseCommits,
   parseStatusOutput,
 } from './plugin-helpers.js';
@@ -148,7 +150,7 @@ export class GitCommand {
 
   status(): StatusParseResult & { exitCode: number } {
     const result = this.run(['status', '--porcelain=1', '--branch', '-z', '-uall']);
-    const parsed = parseStatusOutput(result.stdout);
+    const parsed = applySubmoduleStatusHints(parseStatusOutput(result.stdout), this.listSubmodulePaths());
     return { ...parsed, exitCode: result.status };
   }
 
@@ -272,31 +274,49 @@ export class GitCommand {
     return this.runChecked(args, 'git-pull-failed');
   }
 
-  commit(message: string): GitCommandResult {
-    return this.runChecked(['commit', '-m', message], 'git-commit-failed');
+  /** Returns the current HEAD commit id. */
+  currentHead(): string {
+    return this.runChecked(['rev-parse', 'HEAD'], 'git-head-failed').stdout.trim();
   }
 
-  commitIndex(message?: string, name?: string, email?: string, paths?: string[]): GitCommandResult {
-    const args = ['commit'];
-    
-    if (paths && paths.length > 0) {
-      args.push('--', ...paths);
-    } else {
-      args.push('-a');
-    }
-    
+  /** Creates a commit, optionally limited to the provided paths. */
+  commit(message: string, name?: string, email?: string, paths?: string[]): GitCommandResult {
+    const execArgs = [
+      ...(name ? ['-c', `user.name=${name}`] : []),
+      ...(email ? ['-c', `user.email=${email}`] : []),
+      'commit',
+      '-m',
+      message,
+      ...(paths && paths.length > 0 ? ['--', ...paths] : []),
+    ];
+
+    return this.runChecked(execArgs, 'git-commit-failed');
+  }
+
+  /** Creates a commit from the current index only. */
+  commitIndex(message?: string, name?: string, email?: string): GitCommandResult {
     const commitMessage = message || 'Stage changes';
-    
+
     const execArgs = [
       ...(name ? ['-c', `user.name=${name}`] : []),
       ...(email ? ['-c', `user.email=${email}`] : []),
-      ...args,
-      '-m', commitMessage,
+      'commit',
+      '-m',
+      commitMessage,
     ];
-    
+
     return this.runChecked(execArgs, 'git-commit-failed');
   }
 
+  /** Stages the provided repository-relative paths into the index. */
+  stagePaths(paths: string[]): void {
+    if (paths.length === 0) {
+      return;
+    }
+
+    this.runChecked(['add', '-A', '--', ...paths], 'git-stage-paths-failed');
+  }
+
   listCommits(options: ListCommitsOptions = {}): { commits: CommitEntry[]; exitCode: number } {
     const args = ['log', '--all'];
 
@@ -328,7 +348,7 @@ export class GitCommand {
       args.push(`--until=${options.until_utc}`);
     }
 
-    args.push('--pretty=format:%H%f%x00%aN%x00%aI%x00%P%x1e');
+    args.push('--pretty=format:%H%x00%s%x00%aN%x00%aI%x00%P%x1e');
 
     if (options.branch) {
       args.push(options.branch);
@@ -343,9 +363,13 @@ export class GitCommand {
     return { commits, exitCode: result.status };
   }
 
-  listSubmodules(): SubmoduleEntry[] {
+  /** Reads `.gitmodules` entries indexed by submodule name and path. */
+  private readSubmoduleConfig(): {
+    byName: Map<string, { name: string; path?: string; url?: string; branch?: string }>;
+    byPath: Map<string, { name: string; url?: string; branch?: string }>;
+  } {
     const configResult = this.run(['config', '-f', '.gitmodules', '--null', '--list']);
-    const configByName = new Map<string, { name: string; path?: string; url?: string; branch?: string }>();
+    const byName = new Map<string, { name: string; path?: string; url?: string; branch?: string }>();
 
     if (configResult.status === 0) {
       for (const entry of configResult.stdout.split('\0')) {
@@ -361,23 +385,34 @@ export class GitCommand {
         if (!match) continue;
 
         const [, name, field] = match;
-        const target = configByName.get(name) || { name };
+        const target = byName.get(name) || { name };
 
         if (field === 'path') target.path = value;
         if (field === 'url') target.url = value;
         if (field === 'branch') target.branch = value;
 
-        configByName.set(name, target);
+        byName.set(name, target);
       }
     }
 
-    const configByPath = new Map<string, { name: string; url?: string; branch?: string }>();
-    for (const entry of configByName.values()) {
+    const byPath = new Map<string, { name: string; url?: string; branch?: string }>();
+    for (const entry of byName.values()) {
       if (entry.path) {
-        configByPath.set(entry.path, entry);
+        byPath.set(entry.path, entry);
       }
     }
 
+    return { byName, byPath };
+  }
+
+  /** Returns known submodule paths from `.gitmodules`. */
+  private listSubmodulePaths(): Set<string> {
+    return new Set(this.readSubmoduleConfig().byPath.keys());
+  }
+
+  listSubmodules(): SubmoduleEntry[] {
+    const { byPath: configByPath } = this.readSubmoduleConfig();
+
     const statusResult = this.run(['submodule', 'status', '--recursive']);
     if (statusResult.status !== 0) {
       return [];
@@ -423,11 +458,21 @@ export class GitCommand {
   }
 
   updateSubmodule(path: string): GitCommandResult {
-    return this.runChecked(['submodule', 'update', '--init', '--recursive', '--', path], 'git-submodule-update-failed');
+    return this.runChecked(buildSubmoduleUpdateArgs({ path }), 'git-submodule-update-failed');
   }
 
   updateAllSubmodules(): GitCommandResult {
-    return this.runChecked(['submodule', 'update', '--init', '--recursive'], 'git-submodule-update-failed');
+    return this.runChecked(buildSubmoduleUpdateArgs({}), 'git-submodule-update-failed');
+  }
+
+  /** Updates one submodule from its configured branch recursively. */
+  updateSubmoduleRemote(path: string): GitCommandResult {
+    return this.runChecked(buildSubmoduleUpdateArgs({ path, remote: true }), 'git-submodule-update-remote-failed');
+  }
+
+  /** Updates all submodules from their configured branches recursively. */
+  updateAllSubmodulesRemote(): GitCommandResult {
+    return this.runChecked(buildSubmoduleUpdateArgs({ remote: true }), 'git-submodule-update-remote-failed');
   }
 
   syncSubmodule(path: string): GitCommandResult {
@@ -498,8 +543,11 @@ export class GitCommand {
     return this.run(['hash-object', '-w', '--stdin'], { stdin: content }).stdout.trim();
   }
 
+  /** Stages a textual patch into the index without requiring worktree/index parity. */
   stagePatch(patch: string): void {
-    this.runChecked(['apply', '--3way', '--index'], 'git-stage-patch-failed', { stdin: patch });
+    this.runChecked(['apply', '--cached', '--unidiff-zero'], 'git-stage-patch-failed', {
+      stdin: patch,
+    });
   }
 
   applyReversePatch(patch: string): void {

package/src/plugin-helpers.ts

@@ -74,6 +74,14 @@ export function buildPushArgs(params: RequestParams): string[] {
   return args;
 }
 
+/** Builds `git clone` arguments with recursive submodule initialization enabled. */
+export function buildCloneArgs(params: RequestParams): string[] {
+  const args = ['clone', '--recurse-submodules'];
+  pushOptionalArg(args, params.url);
+  pushOptionalArg(args, params.dest);
+  return args;
+}
+
 /** Builds `git pull --ff-only` arguments while omitting empty optional values. */
 export function buildPullFfOnlyArgs(params: RequestParams): string[] {
   const args = ['pull', '--ff-only'];
@@ -82,6 +90,22 @@ export function buildPullFfOnlyArgs(params: RequestParams): string[] {
   return args;
 }
 
+/** Builds `git submodule update` arguments for pinned or remote-tracking updates. */
+export function buildSubmoduleUpdateArgs(params: RequestParams): string[] {
+  const args = ['submodule', 'update', '--init', '--recursive'];
+
+  if (params.remote === true) {
+    args.push('--remote');
+  }
+
+  const path = asTrimmedString(params.path);
+  if (path) {
+    args.push('--', path);
+  }
+
+  return args;
+}
+
 /** Parses `git status --porcelain=1 --branch -z -uall` output into OpenVCS payloads. */
 export function parseStatusOutput(output: string): StatusParseResult {
   const records = output.split('\0').filter(Boolean);
@@ -164,6 +188,40 @@ export function parseStatusOutput(output: string): StatusParseResult {
   };
 }
 
+/** Applies submodule-specific status labels to known submodule paths. */
+export function applySubmoduleStatusHints(
+  parsed: StatusParseResult,
+  submodulePaths: Iterable<string>,
+): StatusParseResult {
+  const knownPaths = new Set(
+    Array.from(submodulePaths)
+      .map((entry) => asTrimmedString(entry))
+      .filter(Boolean),
+  );
+
+  if (knownPaths.size === 0) {
+    return parsed;
+  }
+
+  return {
+    ...parsed,
+    payload: {
+      ...parsed.payload,
+      files: parsed.payload.files.map((file) => {
+        const path = asTrimmedString(file.path);
+        if (!knownPaths.has(path)) {
+          return file;
+        }
+
+        return {
+          ...file,
+          status: 'S',
+        };
+      }),
+    },
+  };
+}
+
 /** Parses `git log` output into commit entries expected by the host. */
 export function parseCommits(raw: string): CommitEntry[] {
   const records = raw

package/src/plugin-request-handler.ts

@@ -14,10 +14,88 @@ import {
   asString,
   asStringArray,
   asTrimmedString,
+  buildCloneArgs,
+  parseStatusOutput,
 } from './plugin-helpers.js';
 import { GitCommand } from './git.js';
 import type { GitSession } from './plugin-types.js';
 
+/** Describes the Git operations needed to discard a set of paths safely. */
+export interface DiscardPathPlan {
+  /** Restores tracked paths from HEAD in both the index and worktree. */
+  restore: string[];
+  /** Removes newly added index entries before deleting their worktree files. */
+  unstageThenRemove: string[];
+  /** Deletes untracked worktree paths after index state has been corrected. */
+  clean: string[];
+}
+
+/** Reduces a file status string to the primary status code needed for discard routing. */
+function getPrimaryDiscardStatus(status: string): string {
+  const normalized = asTrimmedString(status);
+  if (!normalized) {
+    return 'M';
+  }
+
+  for (const candidate of ['?', 'R', 'C', 'A', 'D', 'U', 'T', 'S', 'M']) {
+    if (normalized.includes(candidate)) {
+      return candidate;
+    }
+  }
+
+  return normalized[0] ?? 'M';
+}
+
+/** Builds a discard plan that handles tracked, added, copied, and renamed paths. */
+export function planDiscardPaths(statusOutput: string): DiscardPathPlan {
+  const restore = new Set<string>();
+  const unstageThenRemove = new Set<string>();
+  const clean = new Set<string>();
+  const parsed = parseStatusOutput(statusOutput);
+
+  for (const file of parsed.payload.files) {
+    const path = asTrimmedString(file.path);
+    const oldPath = asTrimmedString(file.old_path);
+    const primaryStatus = getPrimaryDiscardStatus(file.status);
+
+    if (!path) {
+      continue;
+    }
+
+    if (primaryStatus === '?') {
+      clean.add(path);
+      continue;
+    }
+
+    if (primaryStatus === 'R') {
+      if (oldPath) {
+        restore.add(oldPath);
+      }
+      if (file.staged) {
+        unstageThenRemove.add(path);
+      }
+      clean.add(path);
+      continue;
+    }
+
+    if (primaryStatus === 'C' || primaryStatus === 'A') {
+      if (file.staged) {
+        unstageThenRemove.add(path);
+      }
+      clean.add(path);
+      continue;
+    }
+
+    restore.add(path);
+  }
+
+  return {
+    restore: Array.from(restore),
+    unstageThenRemove: Array.from(unstageThenRemove),
+    clean: Array.from(clean),
+  };
+}
+
 /** Describes the Git runtime services consumed by the VCS delegates. */
 export interface GitRuntimeDependencies {
   /** Allocates a new repository session and returns its id. */
@@ -92,7 +170,7 @@ export class GitVcsDelegates extends VcsDelegateBase<GitRuntimeDependencies> {
     }
 
     const git = this.deps.createGitCommand(process.cwd());
-    const output = git.runChecked(['clone', url, destination], 'vcs-clone-failed');
+    const output = git.runChecked(buildCloneArgs({ url, dest: destination }), 'vcs-clone-failed');
     const lines = `${output.stdout}\n${output.stderr}`
       .split(/\r?\n/g)
       .map((line) => line.trim())
@@ -270,9 +348,13 @@ export class GitVcsDelegates extends VcsDelegateBase<GitRuntimeDependencies> {
     _context: PluginRuntimeContext,
   ): string {
     const git = this.requireGit(params.session_id);
-    const result = git.runChecked(['rev-parse', 'HEAD'], 'git-commit-failed');
-    git.commit(asTrimmedString(params.message));
-    return result.stdout.trim();
+    git.commit(
+      asTrimmedString(params.message),
+      asTrimmedString(params.name),
+      asTrimmedString(params.email),
+      asStringArray(params.paths),
+    );
+    return git.currentHead();
   }
 
   override commitIndex(
@@ -280,14 +362,12 @@ export class GitVcsDelegates extends VcsDelegateBase<GitRuntimeDependencies> {
     _context: PluginRuntimeContext,
   ): string {
     const git = this.requireGit(params.session_id);
-    const result = git.runChecked(['rev-parse', 'HEAD'], 'git-commit-failed');
     git.commitIndex(
       asTrimmedString(params.message),
       asTrimmedString(params.name),
       asTrimmedString(params.email),
-      asStringArray(params.paths),
     );
-    return result.stdout.trim();
+    return git.currentHead();
   }
 
   override getStatusSummary(
@@ -385,6 +465,15 @@ export class GitVcsDelegates extends VcsDelegateBase<GitRuntimeDependencies> {
     return null;
   }
 
+  override stagePaths(
+    params: OpenVcs.VcsStagePathsParams,
+    _context: PluginRuntimeContext,
+  ): null {
+    const git = this.requireGit(params.session_id);
+    git.stagePaths(asStringArray(params.paths));
+    return null;
+  }
+
   override discardPaths(
     params: OpenVcs.VcsDiscardPathsParams,
     _context: PluginRuntimeContext,
@@ -395,7 +484,29 @@ export class GitVcsDelegates extends VcsDelegateBase<GitRuntimeDependencies> {
       return null;
     }
 
-    git.runChecked(['checkout', '--', ...paths], 'git-discard-paths-failed');
+    const status = git.runChecked(
+      ['status', '--porcelain=1', '-z', '-uall', '--', ...paths],
+      'git-discard-paths-failed',
+    );
+    const discardPlan = planDiscardPaths(status.stdout);
+
+    if (discardPlan.unstageThenRemove.length > 0) {
+      git.runChecked(
+        ['rm', '-f', '--cached', '--', ...discardPlan.unstageThenRemove],
+        'git-discard-paths-failed',
+      );
+    }
+
+    if (discardPlan.restore.length > 0) {
+      git.runChecked(
+        ['restore', '--source=HEAD', '--staged', '--worktree', '--', ...discardPlan.restore],
+        'git-discard-paths-failed',
+      );
+    }
+
+    if (discardPlan.clean.length > 0) {
+      git.runChecked(['clean', '-f', '--', ...discardPlan.clean], 'git-discard-paths-failed');
+    }
     return null;
   }
 

package/src/plugin.ts

@@ -58,7 +58,7 @@ export function OnPluginStart(): void {
   const delegates = new GitVcsDelegates(createGitRuntimeDependencies());
   PluginDefinition.vcs = delegates.toDelegates();
 
-  const repoMenu = getOrCreateMenu('repository', 'Repository');
+  const repoMenu = getOrCreateMenu('repository', 'Repository', { surface: 'menubar' });
   if (repoMenu) {
     repoMenu.addItem({ label: 'Edit .gitignore', action: 'repo-edit-gitignore' });
     repoMenu.addItem({ label: 'Edit .gitattributes', action: 'repo-edit-gitattributes' });

package/src/submodules.ts

@@ -44,6 +44,12 @@ function buildSubmoduleRow(entry: SubmoduleEntry) {
     description,
     actions: [
       { type: 'button' as const, id: 'submodules-update', content: 'Update', payload: { path: entry.path } },
+      {
+        type: 'button' as const,
+        id: 'submodules-update-remote',
+        content: 'Update Remote',
+        payload: { path: entry.path },
+      },
       { type: 'button' as const, id: 'submodules-sync', content: 'Sync', payload: { path: entry.path } },
       {
         type: 'button' as const,
@@ -64,33 +70,60 @@ async function openSubmodulesModal(): Promise<unknown> {
 
   const modal = new ModalBuilder('Manage Submodules')
     .text('Review, add, update, sync, and remove submodules without leaving Git.')
+    .text('Use Update Remote to follow each submodule branch configured in .gitmodules.')
     .separator()
-    .input('url', 'Submodule URL', {
-      kind: 'url',
-      placeholder: 'https://example.com/repo.git',
-    })
-    .input('path', 'Submodule Path', {
-      placeholder: 'libs/example',
-    })
-    .input('name', 'Submodule Name', {
-      placeholder: 'example',
-    })
-    .input('branch', 'Branch (optional)', {
-      placeholder: 'main',
-    })
-    .button('submodules-add', 'Add Submodule', {
-      variant: 'primary',
-      align: 'centered',
-    })
-    .button('repo-submodules', 'Refresh', {
-      align: 'centered',
-    })
-    .button('submodules-update-all', 'Update All (Recursive)', {
-      align: 'centered',
-    })
-    .button('submodules-sync-all', 'Sync All', {
-      align: 'centered',
-    })
+    .verticalBox(
+      [
+        {
+          type: 'input' as const,
+          id: 'url',
+          label: 'Submodule URL',
+          kind: 'url' as const,
+          placeholder: 'https://example.com/repo.git',
+        },
+        {
+          type: 'grid' as const,
+          columns: 'minmax(0, 1fr) minmax(0, 1fr)',
+          gap: '.75rem',
+          content: [
+            {
+              type: 'input' as const,
+              id: 'path',
+              label: 'Submodule Path',
+              placeholder: 'libs/example',
+            },
+            {
+              type: 'input' as const,
+              id: 'name',
+              label: 'Submodule Name',
+              placeholder: 'example',
+            },
+          ],
+        },
+        {
+          type: 'input' as const,
+          id: 'branch',
+          label: 'Branch (optional)',
+          placeholder: 'main',
+        },
+      ],
+      { gap: '1rem' },
+    )
+    .horizontalBox(
+      [
+        { type: 'button' as const, id: 'submodules-add', content: 'Add Submodule', variant: 'primary' as const },
+        { type: 'button' as const, id: 'repo-submodules', content: 'Refresh' },
+      ],
+      { gap: '.5rem', align: 'centered', wrap: true },
+    )
+    .horizontalBox(
+      [
+        { type: 'button' as const, id: 'submodules-update-all', content: 'Update All (Recursive)' },
+        { type: 'button' as const, id: 'submodules-update-all-remote', content: 'Update All From Branches' },
+        { type: 'button' as const, id: 'submodules-sync-all', content: 'Sync All' },
+      ],
+      { gap: '.5rem', align: 'centered', wrap: true },
+    )
     .separator()
     .list('submodules', {
       label: 'Submodules',
@@ -109,14 +142,19 @@ async function openRemoveConfirmationModal(path: string, name?: string): Promise
 
   const modal = new ModalBuilder('Confirm Submodule Removal')
     .text(`Remove the submodule at ${submodulePath}? This will deinitialize the submodule, remove it from the index, and delete its working tree entry.`)
-    .button('repo-submodules', 'Back', {
-      align: 'centered',
-    })
-    .button('submodules-remove-confirm', 'Remove Submodule', {
-      variant: 'danger',
-      align: 'centered',
-      payload: { path: submodulePath, name: String(name || '').trim() || undefined },
-    });
+    .horizontalBox(
+      [
+        { type: 'button' as const, id: 'repo-submodules', content: 'Back' },
+        {
+          type: 'button' as const,
+          id: 'submodules-remove-confirm',
+          content: 'Remove Submodule',
+          variant: 'danger' as const,
+          payload: { path: submodulePath, name: String(name || '').trim() || undefined },
+        },
+      ],
+      { gap: '.5rem', align: 'centered', wrap: true },
+    );
 
   return modal.open();
 }
@@ -155,6 +193,15 @@ async function updateSubmodule(payload: ModalActionPayload): Promise<void> {
   await openSubmodulesModal();
 }
 
+/** Updates one submodule from its configured branch and refreshes the toolkit modal. */
+async function updateSubmoduleRemote(payload: ModalActionPayload): Promise<void> {
+  const path = payloadString(payload, 'path');
+  if (!path) return;
+  const git = createGitCommand();
+  git.updateSubmoduleRemote(path);
+  await openSubmodulesModal();
+}
+
 /** Syncs one submodule and refreshes the toolkit modal. */
 async function syncSubmodule(payload: ModalActionPayload): Promise<void> {
   const path = payloadString(payload, 'path');
@@ -171,6 +218,13 @@ async function updateAllSubmodules(): Promise<void> {
   await openSubmodulesModal();
 }
 
+/** Updates all submodules from their configured branches and refreshes the toolkit modal. */
+async function updateAllSubmodulesRemote(): Promise<void> {
+  const git = createGitCommand();
+  git.updateAllSubmodulesRemote();
+  await openSubmodulesModal();
+}
+
 /** Syncs all submodules recursively and refreshes the toolkit modal. */
 async function syncAllSubmodules(): Promise<void> {
   const git = createGitCommand();
@@ -180,7 +234,7 @@ async function syncAllSubmodules(): Promise<void> {
 
 /** Registers the Git submodule toolkit menu and action handlers. */
 export function registerSubmoduleToolkit(): void {
-  const repoMenu = getOrCreateMenu('repository', 'Repository');
+  const repoMenu = getOrCreateMenu('repository', 'Repository', { surface: 'menubar' });
   repoMenu?.addItem({ label: 'Submodules', action: 'repo-submodules' });
 
   registerAction('repo-submodules', async () => {
@@ -196,6 +250,10 @@ export function registerSubmoduleToolkit(): void {
     return updateAllSubmodules();
   });
 
+  registerAction('submodules-update-all-remote', async () => {
+    return updateAllSubmodulesRemote();
+  });
+
   registerAction('submodules-sync-all', async () => {
     return syncAllSubmodules();
   });
@@ -204,6 +262,10 @@ export function registerSubmoduleToolkit(): void {
     return updateSubmodule(asPayload(payload));
   });
 
+  registerAction('submodules-update-remote', async (payload?: unknown) => {
+    return updateSubmoduleRemote(asPayload(payload));
+  });
+
   registerAction('submodules-sync', async (payload?: unknown) => {
     return syncSubmodule(asPayload(payload));
   });