/apps/vscode/proto/cline/worktree.proto

syntax = "proto3";

package cline;

import "cline/common.proto";

option go_package = "github.com/cline/grpc-go/cline";
option java_multiple_files = true;
option java_package = "bot.cline.proto";

// Service for git worktree operations
service WorktreeService {
  // Lists all worktrees in the current repository
  rpc listWorktrees(EmptyRequest) returns (WorktreeList);

  // Creates a new worktree
  rpc createWorktree(CreateWorktreeRequest) returns (WorktreeResult);

  // Deletes an existing worktree
  rpc deleteWorktree(DeleteWorktreeRequest) returns (WorktreeResult);

  // Switches to a different worktree (opens in VS Code)
  rpc switchWorktree(SwitchWorktreeRequest) returns (WorktreeResult);

  // Gets available branches for creating worktrees
  rpc getAvailableBranches(EmptyRequest) returns (BranchList);

  // Gets suggested defaults for creating a new worktree (auto-generated branch name and path)
  rpc getWorktreeDefaults(EmptyRequest) returns (WorktreeDefaults);

  // Gets the status of .worktreeinclude file and .gitignore contents for creating one
  rpc getWorktreeIncludeStatus(EmptyRequest) returns (WorktreeIncludeStatus);

  // Creates a .worktreeinclude file with the provided content
  rpc createWorktreeInclude(CreateWorktreeIncludeRequest) returns (WorktreeResult);

  // Switches to a different branch in the current worktree (git checkout)
  rpc checkoutBranch(CheckoutBranchRequest) returns (WorktreeResult);

  // Merges a worktree's branch into the target branch and optionally deletes the worktree
  rpc mergeWorktree(MergeWorktreeRequest) returns (MergeWorktreeResult);

  // Tracks when the worktrees view is opened (for telemetry)
  rpc trackWorktreeViewOpened(TrackWorktreeViewOpenedRequest) returns (Empty);
}

// Represents a single git worktree
message Worktree {
  string path = 1; // Absolute path to the worktree
  string branch = 2; // Branch name (empty if detached)
  string commit_hash = 3; // Current commit hash
  bool is_current = 4; // Whether this is the current worktree
  bool is_bare = 5; // Whether this is the bare repository
  bool is_detached = 6; // Whether HEAD is detached
  bool is_locked = 7; // Whether the worktree is locked
  optional string lock_reason = 8; // Reason for lock if locked
}

// Response containing list of worktrees
message WorktreeList {
  repeated Worktree worktrees = 1;
  bool is_git_repo = 2; // Whether the current workspace is a git repo
  string error = 3; // Error message if any
  bool is_multi_root = 4; // Whether multiple workspace folders are open (worktrees not supported)
  bool is_subfolder = 5; // Whether workspace is a subfolder of a git repo (not at repo root)
  string git_root_path = 6; // The actual git root path (useful when is_subfolder is true)
}

// Request to create a new worktree
message CreateWorktreeRequest {
  Metadata metadata = 1;
  string path = 2; // Path for the new worktree
  optional string branch = 3; // Branch name (creates new if doesn't exist)
  optional string base_branch = 4; // Base branch for new branch creation
  bool create_new_branch = 5; // Whether to create a new branch
}

// Request to delete a worktree
message DeleteWorktreeRequest {
  Metadata metadata = 1;
  string path = 2; // Path of the worktree to delete
  bool force = 3; // Force deletion even if dirty
  bool delete_branch = 4; // Also delete the branch
  string branch_name = 5; // Name of the branch to delete (required if delete_branch is true)
}

// Request to switch to a worktree
message SwitchWorktreeRequest {
  Metadata metadata = 1;
  string path = 2; // Path of the worktree to switch to
  bool new_window = 3; // Whether to open in a new window
}

// Result of worktree operations
message WorktreeResult {
  bool success = 1;
  string message = 2; // Success or error message
  optional Worktree worktree = 3; // The affected worktree (for create)
}

// List of available branches
message BranchList {
  repeated string local_branches = 1;
  repeated string remote_branches = 2;
  string current_branch = 3;
}

// Suggested defaults for creating a new worktree
message WorktreeDefaults {
  string suggested_branch = 1; // Auto-generated branch name like "worktree/cline-abc12"
  string suggested_path = 2; // Path in Documents/Cline/Worktrees/<project>-<suffix>
}

// Status of .worktreeinclude file
message WorktreeIncludeStatus {
  bool exists = 1; // Whether .worktreeinclude exists
  string gitignore_content = 2; // Content of .gitignore (for prefilling)
  bool has_gitignore = 3; // Whether .gitignore exists
}

// Request to create .worktreeinclude file
message CreateWorktreeIncludeRequest {
  string content = 1; // Content for the .worktreeinclude file
}

// Request to checkout a branch in the current worktree
message CheckoutBranchRequest {
  Metadata metadata = 1;
  string branch = 2; // Branch name to checkout
}

// Request to merge a worktree's branch into target branch
message MergeWorktreeRequest {
  Metadata metadata = 1;
  string worktree_path = 2; // Path of the worktree to merge
  string target_branch = 3; // Branch to merge into (e.g., "main")
  bool delete_after_merge = 4; // Whether to delete the worktree after successful merge
}

// Result of merge operation
message MergeWorktreeResult {
  bool success = 1;
  string message = 2; // Success or error message
  bool has_conflicts = 3; // Whether merge resulted in conflicts
  repeated string conflicting_files = 4; // List of files with conflicts
  string source_branch = 5; // The branch that was merged
  string target_branch = 6; // The branch merged into
}

// Request to track worktree view opened (for telemetry)
message TrackWorktreeViewOpenedRequest {
  string source = 1; // Where the view was opened from: "home_page" or "menu_bar"
}