feat(compare): add compare and do-git workflows

Author: hjun1052

CHANGELOG.md

@@ -7,8 +7,14 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-03-10
+
 ### Added
-- Placeholder for upcoming changes.
+- `xgit compare` for AI-assisted revision/range comparison summaries.
+- `xgit do-git` for recommending Git command sets from natural-language goals.
+
+### Fixed
+- Improved `xgit do-git` recommendations so repositories without remotes prefer local bases like `main` instead of assuming `origin/main`.
 
 ## [0.1.2] - 2026-03-07
 

README.md

@@ -138,8 +138,10 @@ In short: **xgit is not a new VCS**. It is a practical AI layer over the Git you
 - **Commit/review productivity**
   - `xgit commit`: generate high-quality commit messages from diffs
   - `xgit review`: structured risk-focused diff review
+  - `xgit compare`: compare any two revisions/ranges with an AI summary
   - `xgit enhance`: low-risk refactor suggestions from current changes
   - `xgit explain history`: summarize commit timeline, turning points, and hotspots
+  - `xgit do-git`: turn natural-language Git goals into a recommended command set
 
 - **Automation helpers**
   - `xgit test-fix`: propose and validate fixes for failing tests
@@ -185,11 +187,17 @@ xgit commit
 # Review current branch changes vs main
 xgit review --base main
 
+# Compare two revisions with a semantic summary
+xgit compare main HEAD
+
 # Suggest improvements on current diff
 xgit enhance --focus readability
 
 # Explain recent branch history
 xgit explain history main..HEAD --limit 40
+
+# Ask xgit which Git commands to run
+xgit do-git compare my branch with main before I merge
 ```
 
 ### 3) High-impact workflows

cmd/alias.go

@@ -196,6 +196,8 @@ var reservedAliasNames = map[string]bool{
 	"pr-split":      true,
 	"deadcode":      true,
 	"hist-debug":    true,
+	"compare":       true,
+	"do-git":        true,
 	"explain":       true,
 	"why":           true,
 	"map":           true,

cmd/command_execution_test.go

@@ -35,11 +35,16 @@ func TestAdditionalCommandsReachRunE(t *testing.T) {
 	if _, err := execRoot("sync", "--write-report=false"); err != nil {
 		t.Fatalf("expected sync command to work outside git repo, got %v", err)
 	}
+	doGitOut := mustExecRoot(t, "do-git", "show", "me", "the", "commands", "to", "compare", "my", "branch", "with", "main", "--provider", "mock")
+	if !strings.Contains(doGitOut, "Recommended command set:") {
+		t.Fatalf("expected do-git output, got %q", doGitOut)
+	}
 
 	repoRequiredCases := [][]string{
 		{"commit", "--provider", "mock"},
 		{"map"},
 		{"why", "Add", "--provider", "mock"},
+		{"compare", "main", "HEAD", "--provider", "mock"},
 		{"explain", "commit", "HEAD", "--provider", "mock"},
 		{"explain", "file", "README.md", "--provider", "mock"},
 		{"explain", "history", "main..HEAD", "--provider", "mock"},

cmd/command_flags_test.go

@@ -93,4 +93,14 @@ func TestCommandFlagDefaults(t *testing.T) {
 			t.Fatalf("expected hist-debug --flaky-retries default 3, got %d", got)
 		}
 	})
+
+	t.Run("compare defaults", func(t *testing.T) {
+		c := newCompareCommand()
+		if got, _ := c.Flags().GetString("format"); got != "md" {
+			t.Fatalf("expected compare --format default md, got %q", got)
+		}
+		if got, _ := c.Flags().GetStringArray("path"); len(got) != 0 {
+			t.Fatalf("expected compare --path default empty, got %v", got)
+		}
+	})
 }

cmd/compare.go

@@ -0,0 +1,44 @@
+package cmd
+
+import (
+	"context"
+
+	cfgpkg "github.com/hjun1052/xgit/internal/config"
+	"github.com/hjun1052/xgit/internal/workflow"
+	"github.com/spf13/cobra"
+)
+
+func newCompareCommand() *cobra.Command {
+	var format string
+	var paths []string
+
+	cmd := &cobra.Command{
+		Use:   "compare <left> [right]",
+		Short: "Compare revisions with AI summary",
+		Args:  cobra.RangeArgs(1, 2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := cfgpkg.Load()
+			if err != nil {
+				return err
+			}
+
+			left := args[0]
+			right := ""
+			if len(args) == 2 {
+				right = args[1]
+			}
+
+			return workflow.RunCompare(context.Background(), cfg, workflow.CompareOptions{
+				Left:    left,
+				Right:   right,
+				Paths:   paths,
+				Format:  format,
+				Runtime: runtimeOptions(cmd),
+			})
+		},
+	}
+
+	cmd.Flags().StringVar(&format, "format", "md", "Output format: md|json")
+	cmd.Flags().StringArrayVar(&paths, "path", nil, "Limit comparison to specific path(s)")
+	return cmd
+}

cmd/do_git.go

@@ -0,0 +1,28 @@
+package cmd
+
+import (
+	"context"
+	"strings"
+
+	cfgpkg "github.com/hjun1052/xgit/internal/config"
+	"github.com/hjun1052/xgit/internal/workflow"
+	"github.com/spf13/cobra"
+)
+
+func newDoGitCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "do-git <goal...>",
+		Short: "Recommend a git command set from natural language",
+		Args:  cobra.MinimumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cfg, err := cfgpkg.Load()
+			if err != nil {
+				return err
+			}
+			return workflow.RunDoGit(context.Background(), cfg, workflow.DoGitOptions{
+				Goal:    strings.Join(args, " "),
+				Runtime: runtimeOptions(cmd),
+			})
+		},
+	}
+}

cmd/root.go

@@ -27,6 +27,8 @@ func NewRootCommand() *cobra.Command {
 		newPRSplitCommand(),
 		newDeadcodeCommand(),
 		newHistDebugCommand(),
+		newCompareCommand(),
+		newDoGitCommand(),
 		newExplainCommand(),
 		newWhyCommand(),
 		newMapCommand(),
@@ -39,7 +41,7 @@ func NewRootCommand() *cobra.Command {
 	)
 	registerAliasShortcuts(root)
 
-	root.SetHelpTemplate(root.HelpTemplate() + "\nExamples:\n  xgit init --provider openai --api-key-env OPENAI_API_KEY\n  xgit config show\n  xgit alias set ship \"review --base main\" \"commit --apply\"\n  xgit auto --base main\n  xgit auto --base main --aggressive\n  xgit commit\n  xgit enhance --focus readability\n  xgit safe-refactor --base main --focus structure\n  xgit review --base main\n  xgit merge\n  xgit rebase main --auto-resolve --auto-apply\n  xgit pr-split --base main\n  xgit deadcode --lang go\n  xgit explain commit HEAD~1\n  xgit explain history main..HEAD --limit 40\n  xgit map\n  xgit test-fix\n  xgit doc --write\n  xgit feature stash auth src/auth\n  xgit repo merge ../other-repo vendor/other\n  xgit sync --fix\n  xgit doctor\n")
+	root.SetHelpTemplate(root.HelpTemplate() + "\nExamples:\n  xgit init --provider openai --api-key-env OPENAI_API_KEY\n  xgit config show\n  xgit alias set ship \"review --base main\" \"commit --apply\"\n  xgit auto --base main\n  xgit auto --base main --aggressive\n  xgit commit\n  xgit enhance --focus readability\n  xgit safe-refactor --base main --focus structure\n  xgit review --base main\n  xgit compare main HEAD\n  xgit do-git compare my branch with main before I merge\n  xgit merge\n  xgit rebase main --auto-resolve --auto-apply\n  xgit pr-split --base main\n  xgit deadcode --lang go\n  xgit explain commit HEAD~1\n  xgit explain history main..HEAD --limit 40\n  xgit map\n  xgit test-fix\n  xgit doc --write\n  xgit feature stash auth src/auth\n  xgit repo merge ../other-repo vendor/other\n  xgit sync --fix\n  xgit doctor\n")
 	root.SilenceUsage = true
 	root.SilenceErrors = true
 

cmd/root_test.go

@@ -28,7 +28,7 @@ func TestNewRootCommandRegistersCoreCommandsAndFlags(t *testing.T) {
 	required := []string{
 		"config", "alias", "init", "version", "commit", "auto", "enhance",
 		"review", "merge", "rebase", "safe-refactor", "pr-split", "deadcode",
-		"hist-debug", "explain", "why", "map", "test-fix", "doc", "feature",
+		"hist-debug", "compare", "do-git", "explain", "why", "map", "test-fix", "doc", "feature",
 		"repo", "sync", "doctor",
 	}
 	for _, name := range required {

internal/gitutil/git.go

@@ -59,6 +59,34 @@ func RangeDiff(r string) (string, error) {
 	return runGit("diff", r)
 }
 
+func CompareDiff(left, right string, paths []string) (string, error) {
+	left = strings.TrimSpace(left)
+	right = strings.TrimSpace(right)
+	if left == "" && right == "" {
+		return "", errors.New("comparison target is empty")
+	}
+
+	args := []string{"diff"}
+	switch {
+	case left != "" && right != "":
+		args = append(args, left, right)
+	case left != "":
+		if strings.Contains(left, "..") {
+			args = append(args, left)
+		} else {
+			args = append(args, left, "HEAD")
+		}
+	default:
+		args = append(args, "HEAD", right)
+	}
+
+	if len(paths) > 0 {
+		args = append(args, "--")
+		args = append(args, paths...)
+	}
+	return runGit(args...)
+}
+
 func BaseDiff(base string) (string, error) {
 	if strings.TrimSpace(base) == "" {
 		base = "main"
@@ -134,6 +162,36 @@ func CurrentBranch() (string, error) {
 	return strings.TrimSpace(out), nil
 }
 
+func ListRemotes() ([]string, error) {
+	out, err := runGit("remote")
+	if err != nil {
+		return nil, err
+	}
+	return splitNonEmptyLines(out), nil
+}
+
+func RevisionExists(rev string) (bool, error) {
+	rev = strings.TrimSpace(rev)
+	if rev == "" {
+		return false, nil
+	}
+
+	cmd := exec.Command("git", "rev-parse", "--verify", "--quiet", rev)
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		if exitErr, ok := err.(*exec.ExitError); ok && exitErr.ExitCode() == 1 {
+			return false, nil
+		}
+		msg := strings.TrimSpace(stderr.String())
+		if msg == "" {
+			msg = err.Error()
+		}
+		return false, fmt.Errorf("git rev-parse --verify %s failed: %s", rev, msg)
+	}
+	return true, nil
+}
+
 func ResolveRevision(rev string) (string, error) {
 	if strings.TrimSpace(rev) == "" {
 		rev = "HEAD"