Preface¶

When developing with DSH, the working directory of an agent session is usually a git repository. To switch branches, sync with remote, or commit and push current changes, you either switch to the terminal to type commands manually, or ask the agent in the chat to generate and execute commands step-by-step. The former requires leaving the current session, while the latter requires passing through the model at every step. dsh-git-branch-switcher integrates this workflow into the input box toolbar: a capsule button displaying the current branch. Clicking it allows switching branches, fetching remote changes, creating new branches, and switching to them. Below is an introduction to this plugin.

DSH’s philosophy is “Everything is a plugin.” Such tools are community plugins and have no official affiliation with DeepSeek or Fanghui, nor are they part of the official app store.

What is it¶

dsh-git-branch-switcher is a client plugin for DeepSeek Harness, maintained by milestone-17, with the repository address at https://github.com/milestone-17/dsh-git-branch-switcher. It displays the git branch of the current working directory on the left side of the conversation input toolbar and provides operations such as branch switching, remote synchronization, creating new branches, checking commits and pushing, merging, and staging. All git calls are executed locally via subprocess.spawn without a shell. Except for git fetch / git push, it does not access the network or upload any data.

The plugin adopts a Host / Client half-package structure: The Host half, index.js, contains the TypertRemoteService subclass branchSwitcher, responsible for actual git calls; the Client half, client.js, handles the UI and is mounted on the conversation.input.left slot. The current package version is 0.5.2, licensed under MIT. It requires Node.js >= 22 and DSH >= 0.2.1-rc.2 at runtime.

Core Features¶

Capsule Position. Rendered on the left side of the input toolbar, close to the typing position so you don’t have to look up at the session header. Automatically hides in non-git directories. Shows “Detached HEAD” for a detached HEAD. Styles use --dsw-alias-* theme variables, following light/dark themes. When the input line is too narrow, it automatically shrinks to an icon-only view using container queries.

Branch Menu. The top has a search box; local and remote branches are grouped. Current branch is highlighted. Remote tracking branches have a label with the remote name. Switching local branches sorts by most recent commit, max 500 entries. If the target branch is only in remote tracking form, it automatically runs git switch --track to create a local tracking branch.

Remote Sync. One-click execution of git fetch --all --prune. Prompts results upon completion, shows raw git errors on failure.

New Branch and Switch. Menu bottom “＋ New Branch”. Source branch is optional (local or remote tracking), defaults to master (falls back to main, then the current branch). Executes git switch -c <new-branch> <source-branch>. The session working directory switches to the new branch immediately, and the source branch is written to the local config branch.<name>.dsh-base for subsequent merge inference.

Check and Push. “↑ Push” parses workspace changes by lines with types. You can check any part of them, fill in a commit message, then git add → commit → push. Automatically runs push -u origin HEAD if there is no upstream. One-click push of existing commits when workspace is clean. Does not force push if the remote rejects.

Branch Merge. “⇆ Merge” uses a source/target dual dropdown. Target defaults to the branch’s pull source (recorded source → upstream → merge-base → master/main). After successful merge, automatically switches back to the original branch. Returns fast-forward / true / up-to-date mode. On conflicts, lists conflict files and allows one-click abort.

Stash Changes. “≡ Stash” saves the checked items (may include untracked files) as a stash with a description. “Stash List” views involved files one by one; can restore (keep entry) or restore and delete, or delete single items or clear all.

Security Confirmation. When workspace is dirty, confirmations pop up before switching, creating, merging, or restoring stashes. Branch names are whitelisted, rejecting names starting with -, containing whitespace/control characters, .., or ending with ~ ^ :. Push paths are passed as literal pathspec, leaving no room for injection.

Session-level Display. Each session displays the branch independently based on its working directory. The capsule remembers the last state per session, ensuring zero-wait rendering when switching back to a conversation.

Installation and Enabling¶

The README provides four installation methods; the original commands are listed below.

Method 1, Git Source Installation (Recommended):

dsh plugin --profile desktop add github:milestone-17/dsh-git-branch-switcher

Equivalent syntax:

dsh plugin --profile desktop install git+https://github.com/milestone-17/dsh-git-branch-switcher.git

Domestic networks can use mirror channels, content identical to the official repository:

dsh plugin --profile desktop install git+https://ghproxy.net/https://github.com/milestone-17/dsh-git-branch-switcher.git
dsh plugin --profile desktop install git+https://gitclone.com/github.com/milestone-17/dsh-git-branch-switcher.git

Method 2, Pre-built package, no git needed:

dsh plugin --profile desktop add https://github.com/milestone-17/dsh-git-branch-switcher/releases/latest/download/dsh-git-branch-switcher.tgz

Or pin to the current version’s Release package:

dsh plugin --profile desktop add https://github.com/milestone-17/dsh-git-branch-switcher/releases/download/v0.3.0/dsh-git-branch-switcher-0.3.0.tgz

Method 3, Market Index. The repository has market-index.json (DSH official format-1). Deploy it to a static address and add that URL in the “Discover” section of the plugin page:

https://ghproxy.net/https://raw.githubusercontent.com/milestone-17/dsh-git-branch-switcher/master/market-index.json

Method 4, Local Directory Installation:

dsh plugin --profile desktop install /path/to/dsh-git-branch-switcher

After installing / updating / uninstalling, you need to restart the DeepSeek Harness app for changes to take effect. The plugin icon is assembled at app startup. Running sessions are unaffected; they can be restored from the sidebar after restart. If the branch capsule is still not visible after restart, first confirm that the session’s working directory is indeed a git repository.

Typical Usage¶

After installation and restart, as long as the current session’s working directory is a git repository, a branch capsule will appear on the left of the input toolbar. The typical workflow is as follows.

1. Open the capsule menu, confirm the current branch, search and switch to a local branch, or select a remote tracking branch to automatically create a local tracking branch.
2. Click “＋ New Branch”, select a source branch, input the new branch name, and create and switch. The session working directory immediately falls onto the new branch.
3. When there are remote changes that need syncing, you can do a remote sync in the menu before clicking “↑ Push”.
4. If you have unfinished changes before switching branches or pulling code, use “≡ Stash” to save the parts you need from the change list.
5. When merging, use “⇆ Merge” to select source and target; the pull source of the target branch was recorded in local config during branch creation, so it can be inferred automatically.

The object of operation for the above steps is the working directory of the current session. Multiple sessions display their respective branches.

Use Cases and Notes¶

Suitable for users who directly develop against a git repository within DSH, especially in scenarios involving frequent branch switching, needing to sync remotes, or batching changes into commits and pushes. It turns high-frequency branch actions into UI operations, reducing the overhead of repeatedly generating commands in the chat.

Pay attention to a few points when using. The plugin runs with the permissions of the current DSH process and can execute any git commands allowed by that process; you should read the source code and check the license (MIT) before installing. It only runs git locally. git fetch and git push will access the network according to the repository’s own remote configuration. Other commands are local operations, and the plugin does not upload data. Additionally, write operations when the workspace is dirty will pop up a confirmation first. Both branch names and file paths are validated, which is expected behavior rather than a bug.

Summary¶

The value of dsh-git-branch-switcher lies in moving the high-frequency git branch operation out of the terminal and chat commands, turning it into a one-click entry next to the input box. It retains a complete set of capabilities including branch switching, remote sync, creation, checked commits, merging, and staging, and all operations can be traced back to local git. It is an open-source community plugin under the client category.

To learn about complete features and interface details, you can check the directory page https://www.skillhub.cn/plugins/milestone-17/dsh-git-branch-switcher or the repository https://github.com/milestone-17/dsh-git-branch-switcher.