Transparent command output from sync, status, and all git operations

[krisrowe]

Problem

dot sync and dot status suppress the output of underlying git commands, returning only high-level summaries like "Pulled from origin / Pushed to origin" or "Clean — nothing to sync." This makes it impossible to verify what actually happened without running separate commands afterward.

Consequences:

• No way to confirm a push actually landed without checking GitHub separately
• No visibility into whether the repo is ahead, behind, or diverged
• dot status doesn't show ahead/behind counts relative to the remote
• dot sync doesn't show what was pulled, what was pushed, or what was committed
• When something goes wrong, the suppressed output hides the root cause
• Users lose confidence in the tool and resort to manual dot git commands to verify

This undermines the core value proposition: if users can't trust the output, the tool creates anxiety rather than reducing it.

Solution

All commands that run git operations under the hood should expose the raw output of every underlying git command, organized transparently.

Output structure

Each command should produce a sequence of clearly labeled sections showing:

1. The git command that was run (with the repo path for context)
2. The raw output of that command

Example for dot sync:

--- git -C ~/.dotfiles pull --rebase origin main ---
Already up to date.

--- git -C ~/.dotfiles add -A ---

--- git -C ~/.dotfiles commit -m "Sync 3 file(s)" ---
[main abc1234] Sync 3 file(s)
 3 files changed, 45 insertions(+), 12 deletions(-)

--- git -C ~/.dotfiles push origin main ---
To https://github.com/example/dotfiles.git
   def5678..abc1234  main -> main

Example for dot status:

--- git -C ~/.dotfiles status --short ---
 M .config/tool/settings.json

--- git -C ~/.dotfiles rev-list --left-right --count origin/main...main ---
0	1

The second command shows ahead/behind counts (0 behind, 1 ahead in this example).

SDK and MCP tool interface

The SDK functions and MCP tools should return a single parseable JSON document containing an array of sequenced commands and their outputs:

{
  "store": "default",
  "repo": "~/.dotfiles",
  "commands": [
    {
      "command": ["git", "pull", "--rebase", "origin", "main"],
      "returncode": 0,
      "stdout": "Already up to date.\n",
      "stderr": ""
    },
    {
      "command": ["git", "add", "-A"],
      "returncode": 0,
      "stdout": "",
      "stderr": ""
    },
    {
      "command": ["git", "push", "origin", "main"],
      "returncode": 0,
      "stdout": "To https://github.com/example/dotfiles.git\n   def5678..abc1234  main -> main\n",
      "stderr": ""
    }
  ]
}

This avoids brittle mapping or interpretation of git output — the raw output is passed through, and consumers (CLI, MCP clients, AI agents) can format or interpret it as they see fit.

dot status should show ahead/behind

In addition to dirty files, dot status should show the relationship with the remote:

• How many commits ahead of origin
• How many commits behind origin
• Whether the remote is reachable
• Whether a remote is configured at all

This is the minimum information needed to answer "am I backed up?" without running a separate command.

Design principles

• Transparency over abstraction. The tool runs git commands — show them. Don't hide the plumbing behind summaries that may or may not reflect reality.
• No brittle mapping. Don't parse git output to produce a custom summary. Pass through the raw output and let the consumer decide what matters.
• Structured for machines, readable for humans. The JSON array-of-commands format is parseable by MCP clients and AI agents, while the CLI can render it as labeled sections.
• Confidence through visibility. The entire point of a backup tool is peace of mind. Suppressed output undermines that.

Scope

This applies to all commands that invoke git under the hood:

• dot sync (pull, add, commit, push)
• dot status (status, rev-list for ahead/behind)
• dot track / dot untrack (add, rm, commit)

The dot git passthrough command already shows raw output — this proposal extends that transparency to the higher-level commands.