Skip to content

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.rs
index 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 branch
diff --git a/src/commands/list/collect.rs b/src/commands/list/collect.rs
index 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 branch
AheadBehind {
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 branch
BranchDiff {
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.rs
index 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 worktree
pub 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 branch
pub ahead: usize,
- /// Commits behind main
+ /// Commits behind default branch
pub 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.rs
index 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 available
let 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 worktree
IsMain,
- /// 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 changes
SameCommit,
- /// 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 branch
Diverged,
- /// Has commits main doesn't have
+ /// Has commits default branch doesn't have
Ahead,
- /// Missing commits from main
+ /// Missing commits from default branch
Behind,
}
@@ -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 remote
diff --git a/src/verbose_log.rs b/src/verbose_log.rs
index 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 directory
let repo = worktrunk::git::Repository::current().ok()?;