Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: clarify terminology in code comments (#537)
Maximilian Roos88dbdf8959d7
diff --git a/src/cli/step.rs b/src/cli/step.rsindex e5355a7e0..3a4de803b 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -58,7 +58,7 @@ pub enum StepCommand {/// Fast-forward target to current branch////// Updates the local target branch (e.g., `main`) to include current commits.- /// Similar to `git push . HEAD:<target>` but uses+ /// Similar to `git push . HEAD:<target>`, but uses/// `receive.denyCurrentBranch=updateInstead` internally.Push {/// Target branchdiff --git a/src/commands/list/collect.rs b/src/commands/list/collect.rsindex 6a83cf53a..813fa18af 100644--- a/src/commands/list/collect.rs+++ b/src/commands/list/collect.rs@@ -148,29 +148,29 @@ pub(super) enum TaskResult {item_idx: usize,commit: CommitDetails,},- /// Ahead/behind counts vs main+ /// Ahead/behind counts vs default branchAheadBehind {item_idx: usize,counts: AheadBehind,},- /// Whether HEAD's tree SHA matches main's tree SHA (committed content identical)+ /// Whether HEAD's tree SHA matches integration target's tree SHA (committed content identical)CommittedTreesMatch {item_idx: usize,committed_trees_match: bool,},- /// Whether branch has file changes beyond the merge-base (three-dot diff)+ /// Whether branch has file changes beyond the merge-base with integration target (three-dot diff)HasFileChanges {item_idx: usize,has_file_changes: bool,},- /// Whether merging branch into main would add changes (merge simulation)+ /// Whether merging branch into integration target would add changes (merge simulation)WouldMergeAdd {item_idx: usize,would_merge_add: bool,},- /// Whether branch HEAD is ancestor of main (same commit or already merged)+ /// Whether branch HEAD is ancestor of integration target (same commit or already merged)IsAncestor { item_idx: usize, is_ancestor: bool },- /// Line diff vs main branch+ /// Line diff vs default branchBranchDiff {item_idx: usize,branch_diff: BranchDiffTotals,@@ -184,7 +184,7 @@ pub(super) enum TaskResult {working_tree_status: WorkingTreeStatus,has_conflicts: bool,},- /// Potential merge conflicts with main (merge-tree simulation on committed HEAD)+ /// Potential merge conflicts with default branch (merge-tree simulation on committed HEAD)MergeTreeConflicts {item_idx: usize,has_merge_tree_conflicts: bool,@@ -749,8 +749,8 @@ pub fn collect(let branches_without_worktrees = branches_without_worktrees?;let remote_branches = remote_branches?;- // Main worktree is the worktree on the default branch (if exists), else first worktree.- // find_home returns None only if worktrees is empty, which shouldn't happen for wt list.+ // Main worktree is the worktree on the default branch (if exists), else first non-prunable worktree.+ // find_home returns None if all worktrees are prunable or the list is empty.let main_worktree = WorktreeInfo::find_home(&worktrees, &default_branch).cloned().ok_or_else(|| anyhow::anyhow!("No worktrees found"))?;diff --git a/src/commands/list/json_output.rs b/src/commands/list/json_output.rsindex cf63d8e45..baede26e3 100644--- a/src/commands/list/json_output.rs+++ b/src/commands/list/json_output.rs@@ -9,9 +9,9 @@//!//! Fields are organized by concept, matching the status display subcolumns://! - `working_tree`: staged/modified/untracked changes-//! - `main_state`: relationship to main (would_conflict, same_commit, integrated, diverged, ahead, behind)+//! - `main_state`: relationship to the default branch (would_conflict, same_commit, integrated, diverged, ahead, behind)//! - `operation_state`: git operations in progress (conflicts, rebase, merge)-//! - `main`: relationship to main branch (ahead/behind/diff counts)+//! - `main`: relationship to the default branch (ahead/behind/diff counts)//! - `remote`: relationship to tracking branch//! - `worktree`: worktree-specific state (locked, prunable, etc.)@@ -43,8 +43,8 @@ pub struct JsonItem {#[serde(skip_serializing_if = "Option::is_none")]pub working_tree: Option<JsonWorkingTree>,- /// Main branch relationship: would_conflict, same_commit, integrated, diverged, ahead, behind- /// (null for main branch itself)+ /// Default branch relationship: would_conflict, same_commit, integrated, diverged, ahead, behind+ /// (null for default branch itself)#[serde(skip_serializing_if = "Option::is_none")]pub main_state: Option<&'static str>,@@ -57,7 +57,7 @@ pub struct JsonItem {#[serde(skip_serializing_if = "Option::is_none")]pub operation_state: Option<&'static str>,- /// Relationship to main branch (absent when is_main == true)+ /// Relationship to default branch (absent when is_main == true)#[serde(skip_serializing_if = "Option::is_none")]pub main: Option<JsonMain>,@@ -72,10 +72,10 @@ pub struct JsonItem {/// This is the main worktreepub is_main: bool,- /// This is the current worktree (matches $PWD)+ /// This is the current worktree (matches repo discovery path: PWD or `-C`)pub is_current: bool,- /// This was the previous worktree (from wt switch)+ /// This was the previous worktree (from `worktrunk.history`)pub is_previous: bool,/// CI status from PR or branch workflow@@ -137,7 +137,7 @@ pub struct JsonWorkingTree {#[serde(skip_serializing_if = "Option::is_none")]pub diff: Option<JsonDiff>,- /// Lines added/deleted in working tree vs main branch+ /// Lines added/deleted in working tree vs default branch#[serde(skip_serializing_if = "Option::is_none")]pub diff_vs_main: Option<JsonDiff>,}@@ -158,16 +158,16 @@ impl From<LineDiff> for JsonDiff {}}-/// Relationship to main branch+/// Relationship to default branch#[derive(Debug, Clone, Serialize)]pub struct JsonMain {- /// Commits ahead of main+ /// Commits ahead of default branchpub ahead: usize,- /// Commits behind main+ /// Commits behind default branchpub behind: usize,- /// Lines added/deleted vs main branch+ /// Lines added/deleted vs default branch#[serde(skip_serializing_if = "Option::is_none")]pub diff: Option<JsonDiff>,}@@ -191,7 +191,7 @@ pub struct JsonRemote {/// Worktree-specific state#[derive(Debug, Clone, Serialize)]pub struct JsonWorktree {- /// Worktree state: "no_worktree", "branch_worktree_mismatch", "prunable", "locked" (absent when normal)+ /// Worktree state: "branch_worktree_mismatch", "prunable", "locked" (absent when normal)#[serde(skip_serializing_if = "Option::is_none")]pub state: Option<&'static str>,diff --git a/src/commands/list/model.rs b/src/commands/list/model.rsindex 92c1fd4fb..9fa17680b 100644--- a/src/commands/list/model.rs+++ b/src/commands/list/model.rs@@ -195,10 +195,10 @@ pub struct WorktreeData {pub prunable: Option<String>,#[serde(skip_serializing_if = "Option::is_none")]pub working_tree_diff: Option<LineDiff>,- /// Diff between working tree and main branch.+ /// Diff between working tree and default branch./// `None` means "not computed yet" or "not computed" (optimization: skipped when trees differ).- /// `Some(Some((0, 0)))` means working tree matches main exactly.- /// `Some(Some((a, d)))` means a lines added, d deleted vs main.+ /// `Some(Some((0, 0)))` means working tree matches default branch exactly.+ /// `Some(Some((a, d)))` means a lines added, d deleted vs default branch./// `Some(None)` means computation was skipped.#[serde(skip_serializing_if = "Option::is_none")]pub working_tree_diff_with_main: Option<Option<LineDiff>>,@@ -206,10 +206,10 @@ pub struct WorktreeData {#[serde(skip_serializing_if = "GitOperationState::is_none")]pub git_operation: GitOperationState,pub is_main: bool,- /// Whether this is the current worktree (matches $PWD)+ /// Whether this is the current worktree (matches repo discovery path: PWD or `-C`)#[serde(skip_serializing_if = "std::ops::Not::not")]pub is_current: bool,- /// Whether this was the previous worktree (from WT_PREVIOUS_BRANCH)+ /// Whether this was the previous worktree (from `worktrunk.history`)#[serde(skip_serializing_if = "std::ops::Not::not")]pub is_previous: bool,/// Whether the worktree is at an unexpected location (branch-worktree mismatch).@@ -334,23 +334,23 @@ pub struct ListItem {pub counts: Option<AheadBehind>,#[serde(flatten, skip_serializing_if = "Option::is_none")]pub branch_diff: Option<BranchDiffTotals>,- /// Whether HEAD's tree SHA matches main's tree SHA.+ /// Whether HEAD's tree SHA matches the integration target's tree SHA./// True when committed content is identical regardless of commit history./// Internal field used to compute `BranchState::Integrated(TreesMatch)`.#[serde(skip)]pub committed_trees_match: Option<bool>,- /// Whether branch has file changes beyond the merge-base with main.- /// False when three-dot diff (`main...branch`) is empty.+ /// Whether branch has file changes beyond the merge-base with the integration target.+ /// False when three-dot diff (`<integration-target>...branch`) is empty./// Internal field used for integration detection (no unique content).#[serde(skip)]pub has_file_changes: Option<bool>,- /// Whether merging branch into main would add changes (merge simulation).- /// False when `git merge-tree --write-tree main branch` produces same tree as main.- /// Catches squash-merged branches where main advanced.+ /// Whether merging branch into the integration target would add changes (merge simulation).+ /// False when `git merge-tree --write-tree <integration-target> branch` produces the same tree+ /// as the integration target. Catches squash-merged branches where the integration target advanced.#[serde(skip)]pub would_merge_add: Option<bool>,- /// Whether branch HEAD is an ancestor of main (or same commit).- /// True means branch is already part of main's history.+ /// Whether branch HEAD is an ancestor of the integration target (or same commit).+ /// True means branch is already part of the integration target's history./// This is the cheapest integration check (~1ms).#[serde(skip)]pub is_ancestor: Option<bool>,@@ -462,21 +462,21 @@ impl ListItem {/// Determine if the item contains no unique work and can likely be removed.////// Returns:- /// - `Some(true)` - confirmed removable (branch integrated into main)+ /// - `Some(true)` - confirmed removable (branch integrated into integration target)/// - `Some(false)` - confirmed not removable (has unique work)/// - `None` - data still loading, cannot determine yet////// Checks (in order):- /// 1. **Same commit** - branch HEAD is ancestor of main or same commit.- /// The branch is already part of main's history.- /// 2. **No file changes** - three-dot diff (`main...branch`) is empty.+ /// 1. **Same commit** - ahead/behind vs default branch is 0.+ /// The branch is already part of the default branch's history.+ /// 2. **No file changes** - three-dot diff (`<integration-target>...branch`) is empty./// Catches squash-merged branches where commits exist but add no files.- /// 3. **Tree matches main** - tree SHA equals main's tree SHA.+ /// 3. **Tree matches integration target** - tree SHA equals the target's tree SHA./// Catches rebased/squash-merged branches with identical content.- /// 4. **Merge simulation** - merging branch into main wouldn't change main's- /// tree. Catches squash-merged branches where main has advanced.- /// 5. **Working tree matches main** (worktrees only) - uncommitted changes- /// don't diverge from main.+ /// 4. **Merge simulation** - merging branch into the integration target wouldn't change the+ /// target's tree. Catches squash-merged branches where the integration target advanced.+ /// 5. **Working tree matches default branch** (worktrees only) - uncommitted changes+ /// don't diverge from the default branch.pub(crate) fn is_potentially_removable(&self) -> Option<bool> {// Use already-computed status_symbols if availablelet main_state = self.status_symbols.as_ref()?.main_state;@@ -754,11 +754,11 @@ impl ListItem {}}- /// Check if branch content is integrated into main (safe to delete).+ /// Check if branch content is integrated into the default branch (safe to delete).////// Returns `Some(MainState)` only for truly integrated states:- /// - `Empty` = same commit as main with clean working tree- /// - `Integrated(...)` = content in main via different history+ /// - `Empty` = same commit as default branch with clean working tree+ /// - `Integrated(...)` = content in default branch via different history////// Does NOT detect `SameCommit` (same commit with dirty working tree) -/// that's handled separately in the caller since it's not an integration state.@@ -916,46 +916,46 @@ impl serde::Serialize for WorktreeState {}}-/// Main branch relationship state+/// Default branch relationship state///-/// Represents the combined relationship to the main branch in a single position.+/// Represents the combined relationship to the default branch in a single position./// Uses horizontal arrows (vs vertical arrows for Remote column).////// Priority order determines which symbol is shown:-/// 1. IsMain (^) - this IS the main branch+/// 1. IsMain (^) - this IS the main worktree/// 2. WouldConflict (✗) - merge-tree simulation shows conflicts-/// 3. Empty (_) - same commit as main AND clean working tree (safe to delete)-/// 4. SameCommit (–) - same commit as main with uncommitted changes-/// 5. Integrated (⊂) - content is in main via different history-/// 6. Diverged (↕) - both ahead and behind main-/// 7. Ahead (↑) - has commits main doesn't have-/// 8. Behind (↓) - missing commits from main+/// 3. Empty (_) - same commit as default branch AND clean working tree (safe to delete)+/// 4. SameCommit (–) - same commit as default branch with uncommitted changes+/// 5. Integrated (⊂) - content is in default branch via different history+/// 6. Diverged (↕) - both ahead and behind default branch+/// 7. Ahead (↑) - has commits default branch doesn't have+/// 8. Behind (↓) - missing commits from default branch////// The `Integrated` variant carries an [`IntegrationReason`] explaining how the/// content was integrated (ancestor, trees match, no added changes, or merge adds nothing).#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, strum::IntoStaticStr)]#[strum(serialize_all = "snake_case")]pub enum MainState {- /// Normal working branch (up-to-date with main, no special state)+ /// Normal working branch (up-to-date with default branch, no special state)#[default]#[strum(serialize = "")]None,- /// This IS the main branch+ /// This IS the main worktreeIsMain,- /// Merge-tree conflicts with main (simulated via git merge-tree)+ /// Merge-tree conflicts with default branch (simulated via git merge-tree)WouldConflict,- /// Branch HEAD is same commit as main AND working tree is clean (safe to delete)+ /// Branch HEAD is same commit as default branch AND working tree is clean (safe to delete)Empty,- /// Branch HEAD is same commit as main but has uncommitted changes+ /// Branch HEAD is same commit as default branch but has uncommitted changesSameCommit,- /// Content is integrated into main via different history+ /// Content is integrated into default branch via different history#[strum(serialize = "integrated")]Integrated(IntegrationReason),- /// Both ahead and behind main+ /// Both ahead and behind default branchDiverged,- /// Has commits main doesn't have+ /// Has commits default branch doesn't haveAhead,- /// Missing commits from main+ /// Missing commits from default branchBehind,}@@ -1183,7 +1183,7 @@ impl PositionMask {/// Display order (left to right):/// - Working tree: +, !, ? (staged, modified, untracked - NOT mutually exclusive)/// - Worktree state: ✘, ⤴, ⤵, /, ⚑, ⊟, ⊞ (operations + location)-/// - Main state: ^, ✗, _, ⊂, ↕, ↑, ↓ (relationship to main branch - single-stroke vertical arrows)+/// - Main state: ^, ✗, _, ⊂, ↕, ↑, ↓ (relationship to default branch - single-stroke vertical arrows)/// - Upstream divergence: |, ⇅, ⇡, ⇣ (relationship to remote - vertical arrows)/// - User marker: custom labels, emoji///@@ -1201,14 +1201,14 @@ impl PositionMask {////// **Main state (single position with priority):**/// Priority: ^ > ✗ > _ > – > ⊂ > ↕ > ↑ > ↓-/// - ^: This IS the main branch-/// - ✗: Would conflict if merged to main-/// - _: Same commit as main, clean working tree (removable)-/// - –: Same commit as main, uncommitted changes (NOT removable)+/// - ^: This IS the main worktree+/// - ✗: Would conflict if merged to default branch+/// - _: Same commit as default branch, clean working tree (removable)+/// - –: Same commit as default branch, uncommitted changes (NOT removable)/// - ⊂: Content integrated (removable)-/// - ↕: Diverged from main-/// - ↑: Ahead of main-/// - ↓: Behind main+/// - ↕: Diverged from default branch+/// - ↑: Ahead of default branch+/// - ↓: Behind default branch////// **Upstream divergence (enforced by type system):**/// - |: In sync with remotediff --git a/src/verbose_log.rs b/src/verbose_log.rsindex 22a5c7817..61a5a8026 100644--- a/src/verbose_log.rs+++ b/src/verbose_log.rs@@ -66,11 +66,6 @@ pub fn log_file_path() -> Option<PathBuf> {/// Try to create the verbose log file in the repo's wt-logs directory.///-/// TODO: This uses current_dir() which ignores the `-C` flag. If a user runs-/// `wt -C /other/repo list --verbose` from outside the repo, the log file-/// will be created in the wrong location (or not at all). To fix this,-/// verbose_log::init() would need to run after set_base_path(), or accept-/// a repository parameter.fn try_create_log_file() -> Option<(PathBuf, File)> {// Find the git repo from current directorylet repo = worktrunk::git::Repository::current().ok()?;