From 6c856fca136dc9fd95a5ed6eec4c85ebd196612c Mon Sep 17 00:00:00 2001
From: Victor Mota <vimota@gmail.com>
Date: Thu, 19 Feb 2026 10:37:31 -0500
Subject: [PATCH 1/2] feat: add --pull-default flag to workspace start

Add an opt-in --pull-default flag to 'par workspace start' that
automatically pulls each repository's default branch (via origin/HEAD)
before creating workspace branches. This ensures workspace branches
are always based on up-to-date upstream code.

Behavior when --pull-default is passed:
1. Determine each repo's default branch via origin/HEAD
2. Checkout that branch in each repo
3. Run git pull --ff-only to update it
4. Create workspace branches from the updated default branch

The flag is opt-in and preserves existing behavior when not provided.

Closes coplane/par#23
---
 README.md             |  21 +++-
 par/cli.py            |  30 ++++--
 par/operations.py     | 120 ++++++++++++++++++-----
 par/test_workspace.py | 220 ++++++++++++++++++++++++++++++++++++++++++
 par/workspace.py      |  58 ++++++++---
 pyproject.toml        |   2 +-
 6 files changed, 404 insertions(+), 47 deletions(-)
 create mode 100644 par/test_workspace.py

diff --git a/README.md b/README.md
index a43ef8a..d97d6ea 100644
--- a/README.md
+++ b/README.md
@@ -60,6 +60,7 @@ par control-center        # View ALL sessions and workspaces globally with separ
 
 ```bash
 par workspace start feature-auth --repos frontend,backend
+par workspace start feature-auth --repos frontend,backend --pull-default  # Pull default branch first
 par workspace code feature-auth     # Open in VSCode with multi-repo support
 par workspace open feature-auth     # Attach to unified tmux session
 ```
@@ -325,7 +326,7 @@ par workspace cursor feature-auth   # Cursor
 **Create a workspace:**
 
 ```bash
-par workspace start <label> [--path /workspace/root] [--repos repo1,repo2] [--open]
+par workspace start <label> [--path /workspace/root] [--repos repo1,repo2] [--open] [--pull-default]
 ```
 
 **List workspaces (now unified with sessions):**
@@ -534,6 +535,24 @@ Workspaces create branches from the **currently checked out branch** in each rep
 - **Different base branches**: Each repo can be on different branches before workspace creation
 - **Flexible workflows**: Supports GitFlow, GitHub Flow, or custom branching strategies
 
+**Keeping branches up-to-date with `--pull-default`:**
+
+Use the `--pull-default` flag to automatically pull each repository's default branch (determined via `origin/HEAD`) before creating workspace branches:
+
+```bash
+par workspace start feature-auth --repos frontend,backend --pull-default
+```
+
+This will:
+1. Determine each repo's default branch (e.g. `main`) via `origin/HEAD`
+2. Checkout that branch in each repo
+3. Run `git pull --ff-only` to update it
+4. Create workspace branches from the updated default branch
+
+This ensures your workspace branches are always based on the latest upstream code, removing the need to manually checkout and pull each repo beforehand.
+
+> **Note**: If `origin/HEAD` is not set for a repository, run `git remote set-head origin --auto` in that repo first. The pull uses `--ff-only` for safety — if a non-fast-forward update is needed, the operation will fail with a clear error.
+
 ## Advanced Usage
 
 ### Globally Unique Sessions
diff --git a/par/cli.py b/par/cli.py
index 9ade0b1..777d85e 100644
--- a/par/cli.py
+++ b/par/cli.py
@@ -63,8 +63,9 @@ def start(
     path: Annotated[
         Optional[str],
         typer.Option(
-            "--path", "-p",
-            help="Path to git repository (defaults to current directory)"
+            "--path",
+            "-p",
+            help="Path to git repository (defaults to current directory)",
         ),
     ] = None,
     base_branch: Annotated[
@@ -166,8 +167,9 @@ def checkout(
     path: Annotated[
         Optional[str],
         typer.Option(
-            "--path", "-p",
-            help="Path to git repository (defaults to current directory)"
+            "--path",
+            "-p",
+            help="Path to git repository (defaults to current directory)",
         ),
     ] = None,
     label: Annotated[
@@ -246,8 +248,9 @@ def workspace_start(
     path: Annotated[
         Optional[str],
         typer.Option(
-            "--path", "-p",
-            help="Path to workspace directory (defaults to current directory)"
+            "--path",
+            "-p",
+            help="Path to workspace directory (defaults to current directory)",
         ),
     ] = None,
     repos: Annotated[
@@ -262,6 +265,13 @@ def workspace_start(
         bool,
         typer.Option("--open", help="Automatically open the workspace after creation"),
     ] = False,
+    pull_default: Annotated[
+        bool,
+        typer.Option(
+            "--pull-default",
+            help="Pull each repo's default branch (via origin/HEAD) before creating workspace branches",
+        ),
+    ] = False,
 ):
     """
     Start a new multi-repository workspace.
@@ -273,7 +283,13 @@ def workspace_start(
     if repos:
         repo_list = [r.strip() for r in repos.split(",") if r.strip()]
 
-    workspace.start_workspace_session(label, workspace_path=path, repos=repo_list, open_session=open_session)
+    workspace.start_workspace_session(
+        label,
+        workspace_path=path,
+        repos=repo_list,
+        open_session=open_session,
+        pull_default=pull_default,
+    )
 
 
 @workspace_app.command("ls")
diff --git a/par/operations.py b/par/operations.py
index cabf22b..fec344b 100644
--- a/par/operations.py
+++ b/par/operations.py
@@ -29,9 +29,7 @@ def get_current_tmux_session() -> Optional[str]:
         return None
     try:
         result = run_cmd(
-            ["tmux", "display-message", "-p", "#S"], 
-            capture=True, 
-            suppress_output=True
+            ["tmux", "display-message", "-p", "#S"], capture=True, suppress_output=True
         )
         return result.stdout.strip() if result.stdout else None
     except subprocess.CalledProcessError:
@@ -162,7 +160,10 @@ def remove_worktree(worktree_path: Path, repo_root: Optional[Path] = None):
 
 
 def checkout_worktree(
-    branch_name: str, worktree_path: Path, strategy: CheckoutStrategy, repo_root: Optional[Path] = None
+    branch_name: str,
+    worktree_path: Path,
+    strategy: CheckoutStrategy,
+    repo_root: Optional[Path] = None,
 ):
     """Create worktree from existing branch."""
     if repo_root is None:
@@ -307,13 +308,21 @@ def _update_control_center_windows(session_name: str, contexts_data: List[dict])
     """Update control center windows to match current contexts."""
     # Get current windows in the control center session
     try:
-        result = run_cmd([
-            "tmux", "list-windows", "-t", session_name, "-F", "#{window_index}:#{window_name}"
-        ], capture=True)
+        result = run_cmd(
+            [
+                "tmux",
+                "list-windows",
+                "-t",
+                session_name,
+                "-F",
+                "#{window_index}:#{window_name}",
+            ],
+            capture=True,
+        )
         current_windows = {}
-        for line in result.stdout.strip().split('\n'):
-            if ':' in line:
-                index, name = line.split(':', 1)
+        for line in result.stdout.strip().split("\n"):
+            if ":" in line:
+                index, name = line.split(":", 1)
                 current_windows[name] = int(index)
     except Exception:
         # If we can't get windows, fall back to recreating the session
@@ -336,10 +345,18 @@ def _update_control_center_windows(session_name: str, contexts_data: List[dict])
     for i, context in enumerate(contexts_data):
         if context["name"] not in existing_names:
             # Create new window
-            run_cmd([
-                "tmux", "new-window", "-t", session_name,
-                "-n", context["name"], "-c", context["path"]
-            ])
+            run_cmd(
+                [
+                    "tmux",
+                    "new-window",
+                    "-t",
+                    session_name,
+                    "-n",
+                    context["name"],
+                    "-c",
+                    context["path"],
+                ]
+            )
         # If window exists, we could update its working directory, but tmux doesn't
         # have a direct command for this. The window will retain its original path.
 
@@ -369,7 +386,8 @@ def open_control_center(contexts_data: List[dict]):
     # Check if control center already exists
     if tmux_session_exists(cc_session_name):
         typer.secho(
-            f"Updating existing control center '{cc_session_name}' with current sessions", fg="cyan"
+            f"Updating existing control center '{cc_session_name}' with current sessions",
+            fg="cyan",
         )
         if _update_control_center_windows(cc_session_name, contexts_data):
             open_tmux_session(cc_session_name)
@@ -381,24 +399,80 @@ def open_control_center(contexts_data: List[dict]):
     create_tmux_session(cc_session_name, Path(first_context["path"]))
 
     # Rename first window
-    run_cmd([
-        "tmux", "rename-window", "-t", f"{cc_session_name}:0", first_context["name"]
-    ])
+    run_cmd(
+        ["tmux", "rename-window", "-t", f"{cc_session_name}:0", first_context["name"]]
+    )
 
     # Create additional windows for remaining contexts
     for context in contexts_data[1:]:
-        run_cmd([
-            "tmux", "new-window", "-t", cc_session_name,
-            "-n", context["name"], "-c", context["path"]
-        ])
+        run_cmd(
+            [
+                "tmux",
+                "new-window",
+                "-t",
+                cc_session_name,
+                "-n",
+                context["name"],
+                "-c",
+                context["path"],
+            ]
+        )
 
     # Select window 0 before attaching
     run_cmd(["tmux", "select-window", "-t", f"{cc_session_name}:0"])
 
-    typer.secho(f"Created control center with {len(contexts_data)} windows.", fg="green")
+    typer.secho(
+        f"Created control center with {len(contexts_data)} windows.", fg="green"
+    )
     open_tmux_session(cc_session_name)
 
 
+def get_default_branch(repo_path: Path) -> str:
+    """Get the default branch name for a repository via origin/HEAD."""
+    try:
+        result = run_cmd(
+            ["git", "symbolic-ref", "refs/remotes/origin/HEAD"],
+            cwd=repo_path,
+            suppress_output=True,
+        )
+        # Output is like "refs/remotes/origin/main" -> extract "main"
+        return result.stdout.strip().removeprefix("refs/remotes/origin/")
+    except Exception:
+        typer.secho(
+            f"Could not determine default branch for {repo_path.name}. "
+            "Try running 'git remote set-head origin --auto' in that repo.",
+            fg="red",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+
+def pull_default_branch(repo_path: Path, branch_name: str):
+    """Checkout the default branch and pull with --ff-only."""
+    try:
+        run_cmd(["git", "checkout", branch_name], cwd=repo_path, suppress_output=True)
+    except Exception:
+        typer.secho(
+            f"Failed to checkout '{branch_name}' in {repo_path.name}. "
+            "Ensure working tree is clean.",
+            fg="red",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    try:
+        run_cmd(["git", "pull", "--ff-only"], cwd=repo_path, suppress_output=True)
+        typer.secho(f"Pulled '{branch_name}' in {repo_path.name}", fg="cyan")
+    except Exception:
+        typer.secho(
+            f"Failed to pull '{branch_name}' in {repo_path.name}. "
+            "Non-fast-forward updates are not supported.",
+            fg="red",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+
 def create_workspace_worktree(
     repo_path: Path, label: str, worktree_path: Path, base_branch: Optional[str] = None
 ):
diff --git a/par/test_workspace.py b/par/test_workspace.py
new file mode 100644
index 0000000..ad1cfb9
--- /dev/null
+++ b/par/test_workspace.py
@@ -0,0 +1,220 @@
+"""Tests for workspace pull-default behavior."""
+
+import subprocess
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from . import cli, operations, workspace
+
+# --- get_default_branch tests ---
+
+
+@patch("par.operations.run_cmd")
+def test_get_default_branch_returns_branch_name(mock_run_cmd):
+    """get_default_branch extracts branch name from symbolic-ref output."""
+    mock_run_cmd.return_value = MagicMock(stdout="refs/remotes/origin/main\n")
+    result = operations.get_default_branch(Path("/tmp/repo"))
+    assert result == "main"
+    mock_run_cmd.assert_called_once_with(
+        ["git", "symbolic-ref", "refs/remotes/origin/HEAD"],
+        cwd=Path("/tmp/repo"),
+        suppress_output=True,
+    )
+
+
+@patch("par.operations.run_cmd")
+def test_get_default_branch_handles_develop(mock_run_cmd):
+    """get_default_branch works with non-main default branches."""
+    mock_run_cmd.return_value = MagicMock(stdout="refs/remotes/origin/develop\n")
+    result = operations.get_default_branch(Path("/tmp/repo"))
+    assert result == "develop"
+
+
+@patch("par.operations.run_cmd")
+def test_get_default_branch_exits_on_failure(mock_run_cmd):
+    """get_default_branch raises Exit when origin/HEAD is not set."""
+    mock_run_cmd.side_effect = subprocess.CalledProcessError(1, "git")
+    with pytest.raises(typer.Exit):
+        operations.get_default_branch(Path("/tmp/repo"))
+
+
+# --- pull_default_branch tests ---
+
+
+@patch("par.operations.run_cmd")
+def test_pull_default_branch_checkouts_and_pulls(mock_run_cmd):
+    """pull_default_branch runs checkout then pull --ff-only."""
+    mock_run_cmd.return_value = MagicMock()
+    operations.pull_default_branch(Path("/tmp/repo"), "main")
+    assert mock_run_cmd.call_count == 2
+    mock_run_cmd.assert_any_call(
+        ["git", "checkout", "main"], cwd=Path("/tmp/repo"), suppress_output=True
+    )
+    mock_run_cmd.assert_any_call(
+        ["git", "pull", "--ff-only"], cwd=Path("/tmp/repo"), suppress_output=True
+    )
+
+
+@patch("par.operations.run_cmd")
+def test_pull_default_branch_exits_on_checkout_failure(mock_run_cmd):
+    """pull_default_branch exits if checkout fails (e.g., dirty tree)."""
+    mock_run_cmd.side_effect = subprocess.CalledProcessError(1, "git")
+    with pytest.raises(typer.Exit):
+        operations.pull_default_branch(Path("/tmp/repo"), "main")
+
+
+@patch("par.operations.run_cmd")
+def test_pull_default_branch_exits_on_pull_failure(mock_run_cmd):
+    """pull_default_branch exits if pull --ff-only fails (non-ff)."""
+    # Checkout succeeds, pull fails
+    mock_run_cmd.side_effect = [MagicMock(), subprocess.CalledProcessError(1, "git")]
+    with pytest.raises(typer.Exit):
+        operations.pull_default_branch(Path("/tmp/repo"), "main")
+
+
+# --- CLI --pull-default flag tests ---
+
+
+@patch("par.cli.workspace.start_workspace_session")
+def test_cli_workspace_start_forwards_pull_default(mock_start):
+    """CLI workspace start passes --pull-default through."""
+    runner = CliRunner()
+    result = runner.invoke(
+        cli.app,
+        ["workspace", "start", "my-ws", "--pull-default"],
+    )
+
+    assert result.exit_code == 0
+    mock_start.assert_called_once_with(
+        "my-ws", workspace_path=None, repos=None, open_session=False, pull_default=True
+    )
+
+
+@patch("par.cli.workspace.start_workspace_session")
+def test_cli_workspace_start_pull_default_off_by_default(mock_start):
+    """pull_default defaults to False when flag is not provided."""
+    runner = CliRunner()
+    result = runner.invoke(
+        cli.app,
+        ["workspace", "start", "my-ws"],
+    )
+
+    assert result.exit_code == 0
+    mock_start.assert_called_once_with(
+        "my-ws", workspace_path=None, repos=None, open_session=False, pull_default=False
+    )
+
+
+# --- Workspace start integration with pull_default ---
+
+
+@patch("par.workspace.open_workspace_session")
+@patch("par.workspace._add_workspace_session")
+@patch("par.workspace.initialization.run_initialization")
+@patch("par.workspace.initialization.load_par_config", return_value=None)
+@patch("par.workspace.initialization.copy_included_files")
+@patch("par.workspace.operations.create_tmux_session")
+@patch("par.workspace.operations.create_workspace_worktree")
+@patch("par.workspace.operations.tmux_session_exists", return_value=False)
+@patch("par.workspace.operations.pull_default_branch")
+@patch("par.workspace.operations.get_default_branch", return_value="main")
+@patch("par.workspace.core._validate_label_unique", return_value=True)
+@patch("par.workspace.utils.get_workspace_worktree_path")
+@patch("par.workspace.utils.get_workspace_session_name", return_value="ws-session")
+def test_workspace_start_with_pull_default(
+    mock_session_name,
+    mock_wt_path,
+    mock_validate,
+    mock_get_default,
+    mock_pull_default,
+    mock_tmux_exists,
+    mock_create_wt,
+    mock_create_tmux,
+    mock_copy_includes,
+    mock_load_config,
+    mock_run_init,
+    mock_add_ws,
+    mock_open_ws,
+    tmp_path,
+):
+    """start_workspace_session with pull_default=True pulls before creating worktrees."""
+    # Setup: create fake repo dirs
+    repo_a = tmp_path / "repo-a"
+    repo_a.mkdir()
+    (repo_a / ".git").mkdir()
+    repo_b = tmp_path / "repo-b"
+    repo_b.mkdir()
+    (repo_b / ".git").mkdir()
+
+    mock_wt_path.return_value = tmp_path / "worktrees" / "test-ws" / "repo"
+
+    workspace.start_workspace_session(
+        "test-ws",
+        workspace_path=str(tmp_path),
+        repos=["repo-a", "repo-b"],
+        pull_default=True,
+    )
+
+    # Verify get_default_branch called for each repo
+    assert mock_get_default.call_count == 2
+    mock_get_default.assert_any_call(repo_a)
+    mock_get_default.assert_any_call(repo_b)
+
+    # Verify pull_default_branch called for each repo with the resolved branch
+    assert mock_pull_default.call_count == 2
+    mock_pull_default.assert_any_call(repo_a, "main")
+    mock_pull_default.assert_any_call(repo_b, "main")
+
+    # Verify worktrees created with base_branch="main"
+    for c in mock_create_wt.call_args_list:
+        assert (
+            c.kwargs.get("base_branch") == "main"
+            or c[0][-1] == "main"
+            or "base_branch" in str(c)
+        )
+
+
+@patch("par.workspace._add_workspace_session")
+@patch("par.workspace.initialization.load_par_config", return_value=None)
+@patch("par.workspace.initialization.copy_included_files")
+@patch("par.workspace.operations.create_tmux_session")
+@patch("par.workspace.operations.create_workspace_worktree")
+@patch("par.workspace.operations.tmux_session_exists", return_value=False)
+@patch("par.workspace.core._validate_label_unique", return_value=True)
+@patch("par.workspace.utils.get_workspace_worktree_path")
+@patch("par.workspace.utils.get_workspace_session_name", return_value="ws-session")
+def test_workspace_start_without_pull_default_skips_pull(
+    mock_session_name,
+    mock_wt_path,
+    mock_validate,
+    mock_create_wt,
+    mock_tmux_exists,
+    mock_create_tmux,
+    mock_copy_includes,
+    mock_load_config,
+    mock_add_ws,
+    tmp_path,
+):
+    """start_workspace_session with pull_default=False does NOT call pull operations."""
+    repo_a = tmp_path / "repo-a"
+    repo_a.mkdir()
+    (repo_a / ".git").mkdir()
+
+    mock_wt_path.return_value = tmp_path / "worktrees" / "test-ws" / "repo"
+
+    with (
+        patch("par.workspace.operations.get_default_branch") as mock_get_default,
+        patch("par.workspace.operations.pull_default_branch") as mock_pull,
+    ):
+        workspace.start_workspace_session(
+            "test-ws",
+            workspace_path=str(tmp_path),
+            repos=["repo-a"],
+            pull_default=False,
+        )
+        mock_get_default.assert_not_called()
+        mock_pull.assert_not_called()
diff --git a/par/workspace.py b/par/workspace.py
index baecb29..a9cf936 100644
--- a/par/workspace.py
+++ b/par/workspace.py
@@ -24,23 +24,33 @@ def _add_workspace_session(workspace_data: Dict[str, Any]):
     core._add_session(workspace_data)
 
 
-
-
 # Workspace operations
 def start_workspace_session(
-    label: str, workspace_path: Optional[str] = None, repos: Optional[List[str]] = None, open_session: bool = False
+    label: str,
+    workspace_path: Optional[str] = None,
+    repos: Optional[List[str]] = None,
+    open_session: bool = False,
+    pull_default: bool = False,
 ):
     """Start a new workspace with multiple repositories."""
     # Validate label is globally unique
     if not _validate_workspace_label_unique(label):
-        typer.secho(f"Error: Label '{label}' already exists. Labels must be globally unique.", fg="red", err=True)
+        typer.secho(
+            f"Error: Label '{label}' already exists. Labels must be globally unique.",
+            fg="red",
+            err=True,
+        )
         raise typer.Exit(1)
 
     # Resolve workspace directory
     if workspace_path:
         workspace_root = Path(workspace_path).resolve()
         if not workspace_root.exists():
-            typer.secho(f"Error: Directory '{workspace_path}' does not exist.", fg="red", err=True)
+            typer.secho(
+                f"Error: Directory '{workspace_path}' does not exist.",
+                fg="red",
+                err=True,
+            )
             raise typer.Exit(1)
     else:
         workspace_root = Path.cwd()
@@ -63,7 +73,7 @@ def start_workspace_session(
         repo_paths = []
         for repo_spec in repos:
             # Support both absolute paths and relative names
-            if repo_spec.startswith('/') or Path(repo_spec).is_absolute():
+            if repo_spec.startswith("/") or Path(repo_spec).is_absolute():
                 # Absolute path provided
                 repo_path = Path(repo_spec).resolve()
                 repo_name = repo_path.name
@@ -74,7 +84,9 @@ def start_workspace_session(
 
             if not repo_path.exists():
                 typer.secho(
-                    f"Error: Repository path '{repo_path}' does not exist.", fg="red", err=True
+                    f"Error: Repository path '{repo_path}' does not exist.",
+                    fg="red",
+                    err=True,
                 )
                 raise typer.Exit(1)
             if not (repo_path / ".git").exists():
@@ -86,6 +98,15 @@ def start_workspace_session(
             repo_names.append(repo_name)
             repo_paths.append(repo_path)
 
+    # If --pull-default, update each repo's default branch before creating worktrees
+    default_branches: dict[str, str] = {}
+    if pull_default:
+        typer.secho("Pulling default branch for each repository...", fg="cyan")
+        for repo_path in repo_paths:
+            default_branch = operations.get_default_branch(repo_path)
+            operations.pull_default_branch(repo_path, default_branch)
+            default_branches[str(repo_path)] = default_branch
+
     session_name = utils.get_workspace_session_name(workspace_root, label)
 
     # Check for conflicts
@@ -107,15 +128,16 @@ def start_workspace_session(
             )
             raise typer.Exit(1)
 
-        # Create resources
-        operations.create_workspace_worktree(repo_path, label, worktree_path)
+        # Create resources - use pulled default branch as base when --pull-default
+        base_branch = default_branches.get(str(repo_path))
+        operations.create_workspace_worktree(
+            repo_path, label, worktree_path, base_branch=base_branch
+        )
 
         # Copy includes for this repository
         config = initialization.load_par_config(repo_path)
         if config:
-            initialization.copy_included_files(
-                config, repo_path, worktree_path
-            )
+            initialization.copy_included_files(config, repo_path, worktree_path)
 
         repos_data.append(
             {
@@ -176,7 +198,9 @@ def start_workspace_session(
 def list_workspace_sessions():
     """List all workspace sessions globally (now shown in main par ls)."""
     all_sessions = core._get_all_sessions()
-    workspace_sessions = {k: v for k, v in all_sessions.items() if v.get("session_type") == "workspace"}
+    workspace_sessions = {
+        k: v for k, v in all_sessions.items() if v.get("session_type") == "workspace"
+    }
 
     if not workspace_sessions:
         typer.secho("No workspace sessions found.", fg="yellow")
@@ -184,7 +208,9 @@ def list_workspace_sessions():
         return
 
     console = Console()
-    table = Table(show_header=True, header_style="bold magenta", title="Workspace Sessions")
+    table = Table(
+        show_header=True, header_style="bold magenta", title="Workspace Sessions"
+    )
     table.add_column("Label", style="cyan", no_wrap=True)
     table.add_column("Repositories", style="green")
     table.add_column("Session", style="magenta", no_wrap=True)
@@ -225,7 +251,9 @@ def remove_all_workspace_sessions():
     """Remove all workspace sessions globally."""
     # Get all workspace sessions from global sessions
     all_sessions = core._get_all_sessions()
-    workspace_sessions = {k: v for k, v in all_sessions.items() if v.get("session_type") == "workspace"}
+    workspace_sessions = {
+        k: v for k, v in all_sessions.items() if v.get("session_type") == "workspace"
+    }
 
     if not workspace_sessions:
         typer.secho("No workspace sessions to remove.", fg="yellow")
diff --git a/pyproject.toml b/pyproject.toml
index 69174f3..03c4e13 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "par-cli"
-version = "0.2.1"
+version = "0.2.2"
 description = "CLI for parallel development workflows with isolated Git worktrees and tmux sessions, tailored for agentic coding."
 authors = [ { name="Victor", email="vimota@gmail.com" } ]
 requires-python = ">=3.12"

From d05f3dd29f79d4045d1c10ea4cdd7c1c14db1e4d Mon Sep 17 00:00:00 2001
From: userhas404d <29389186+userhas404d@users.noreply.github.com>
Date: Fri, 3 Apr 2026 10:17:09 -0400
Subject: [PATCH 2/2] feat: add --pull-default flag to par start

Add --pull-default to single-repo 'par start' command, mirroring the
existing workspace behavior. When set, the default branch is detected
via origin/HEAD, pulled with --ff-only, and used as the base for the
new worktree branch. An explicit --base still takes precedence.

- Add pull_default param to core.start_session()
- Add --pull-default CLI flag to start/create commands
- Add 4 new tests covering CLI forwarding and core behavior
- Update README with single-repo --pull-default docs
---
 README.md         |   8 +++
 par/cli.py        |   8 +++
 par/core.py       | 114 +++++++++++++++++++++++++--------------
 par/test_start.py | 135 +++++++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 225 insertions(+), 40 deletions(-)

diff --git a/README.md b/README.md
index d97d6ea..a50355b 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ https://github.com/user-attachments/assets/88eb4aed-c00d-4238-b1a9-bcaa34c975c3
 # From within a git repository
 par start feature-auth    # Creates worktree, branch, and tmux session
 par start feature-auth --base develop
+par start feature-auth --pull-default  # Pull default branch first
 
 # From anywhere on your system
 par start bugfix-login --path /path/to/repo
@@ -135,6 +136,7 @@ Create a new isolated development environment:
 # From within a git repository
 par start my-feature
 par start my-feature --base develop
+par start my-feature --pull-default
 
 # From anywhere, specifying the repository path
 par start my-feature --path /path/to/your/git/repo
@@ -143,6 +145,8 @@ par start my-feature -p ~/projects/my-app
 
 By default, `par start` branches from the current `HEAD` commit. Use `--base` to branch from a specific branch/reference. `par` resolves the base to a commit SHA, so uncommitted changes in your current worktree do not affect the new branch.
 
+Use `--pull-default` to pull the repository's default branch (determined via `origin/HEAD`) before creating the worktree branch. If no `--base` is provided, the new branch will be based on the freshly pulled default branch. If both `--pull-default` and `--base` are provided, the default branch is still pulled but `--base` takes precedence for the branch point.
+
 If the label already matches an existing local branch, `par start <label>` will reuse that branch and create a worktree with it checked out instead of creating a new branch.
 If no local branch exists but `origin/<label>` exists, `par` fetches it and creates the worktree from `origin/<label>`.
 
@@ -540,6 +544,10 @@ Workspaces create branches from the **currently checked out branch** in each rep
 Use the `--pull-default` flag to automatically pull each repository's default branch (determined via `origin/HEAD`) before creating workspace branches:
 
 ```bash
+# Single-repo session
+par start feature-auth --pull-default
+
+# Multi-repo workspace
 par workspace start feature-auth --repos frontend,backend --pull-default
 ```
 
diff --git a/par/cli.py b/par/cli.py
index 777d85e..5bec505 100644
--- a/par/cli.py
+++ b/par/cli.py
@@ -82,6 +82,13 @@ def start(
             "--open", help="Automatically open/attach to the session after creation."
         ),
     ] = False,
+    pull_default: Annotated[
+        bool,
+        typer.Option(
+            "--pull-default",
+            help="Pull the default branch (via origin/HEAD) before creating the worktree branch",
+        ),
+    ] = False,
 ):
     """
     Start a new git worktree and tmux session.
@@ -94,6 +101,7 @@ def start(
         repo_path=path,
         open_session=open_session,
         base_branch=base_branch,
+        pull_default=pull_default,
     )
 
 
diff --git a/par/core.py b/par/core.py
index 99e02e9..903167c 100644
--- a/par/core.py
+++ b/par/core.py
@@ -39,7 +39,9 @@ def _load_global_state() -> Dict[str, Any]:
                 state["workspaces"] = {}
             return state
     except json.JSONDecodeError:
-        typer.secho("Warning: Global state file corrupted. Starting fresh.", fg="yellow")
+        typer.secho(
+            "Warning: Global state file corrupted. Starting fresh.", fg="yellow"
+        )
         return {"sessions": {}, "workspaces": {}}
 
 
@@ -73,12 +75,12 @@ def _resolve_previous_session_label() -> str:
     if not previous_session:
         typer.secho("Error: No previous session found.", fg="red", err=True)
         raise typer.Exit(1)
-    
+
     # Check if we're already in the previous session
     current_tmux_session = operations.get_current_tmux_session()
     if not current_tmux_session:
         return previous_session
-    
+
     # Find which of our tracked sessions corresponds to the current tmux session
     state = _load_global_state()
     current_par_session = None
@@ -86,16 +88,20 @@ def _resolve_previous_session_label() -> str:
         if session_data["tmux_session_name"] == current_tmux_session:
             current_par_session = session_label
             break
-    
+
     # If we're already in the "previous" session, go to the last session instead
     if current_par_session == previous_session:
         last_session = state.get("last_session")
         if last_session and last_session != current_par_session:
             return last_session
         else:
-            typer.secho("Error: Cannot determine which session to switch to.", fg="red", err=True)
+            typer.secho(
+                "Error: Cannot determine which session to switch to.",
+                fg="red",
+                err=True,
+            )
             raise typer.Exit(1)
-    
+
     return previous_session
 
 
@@ -133,8 +139,10 @@ def _migrate_legacy_state() -> Dict[str, Any]:
                         "tmux_session_name": session_data["tmux_session_name"],
                         "branch_name": session_data["branch_name"],
                         "created_at": session_data["created_at"],
-                        "session_type": "checkout" if session_data.get("is_checkout") else "session",
-                        "checkout_target": session_data.get("checkout_target")
+                        "session_type": "checkout"
+                        if session_data.get("is_checkout")
+                        else "session",
+                        "checkout_target": session_data.get("checkout_target"),
                     }
         except (json.JSONDecodeError, FileNotFoundError):
             pass
@@ -151,8 +159,10 @@ def _migrate_legacy_state() -> Dict[str, Any]:
                     # Create globally unique label if collision
                     global_label = label
                     counter = 1
-                    while (global_label in migrated["sessions"] or
-                           global_label in migrated["workspaces"]):
+                    while (
+                        global_label in migrated["sessions"]
+                        or global_label in migrated["workspaces"]
+                    ):
                         workspace_name = Path(workspace_root).name
                         global_label = f"{label}-{workspace_name.lower()}-{counter}"
                         counter += 1
@@ -162,7 +172,7 @@ def _migrate_legacy_state() -> Dict[str, Any]:
                         "workspace_root": workspace_data["workspace_root"],
                         "session_name": workspace_data["session_name"],
                         "repos": workspace_data["repos"],
-                        "created_at": workspace_data["created_at"]
+                        "created_at": workspace_data["created_at"],
                     }
         except (json.JSONDecodeError, FileNotFoundError):
             pass
@@ -177,7 +187,9 @@ def _migrate_legacy_state() -> Dict[str, Any]:
         if legacy_workspace_file.exists():
             shutil.copy2(legacy_workspace_file, backup_dir / "workspaces.json.backup")
 
-        typer.secho(f"Migrated legacy state files. Backups saved to {backup_dir}", fg="green")
+        typer.secho(
+            f"Migrated legacy state files. Backups saved to {backup_dir}", fg="green"
+        )
 
     return migrated
 
@@ -218,19 +230,22 @@ def _get_session(label: str) -> Optional[Dict[str, Any]]:
     return state["sessions"].get(label)
 
 
-
-
 # Session operations - now globally scoped
 def start_session(
     label: str,
     repo_path: Optional[str] = None,
     open_session: bool = False,
     base_branch: Optional[str] = None,
+    pull_default: bool = False,
 ):
     """Start a new git worktree and tmux session."""
     # Validate label is globally unique
     if not _validate_label_unique(label):
-        typer.secho(f"Error: Label '{label}' already exists. Labels must be globally unique.", fg="red", err=True)
+        typer.secho(
+            f"Error: Label '{label}' already exists. Labels must be globally unique.",
+            fg="red",
+            err=True,
+        )
         raise typer.Exit(1)
 
     # Resolve repository path
@@ -251,6 +266,14 @@ def start_session(
         typer.secho(f"Error: tmux session '{session_name}' exists.", fg="red", err=True)
         raise typer.Exit(1)
 
+    # If --pull-default, update the default branch before creating the worktree
+    if pull_default:
+        default_branch = operations.get_default_branch(repo_root)
+        operations.pull_default_branch(repo_root, default_branch)
+        # Use the pulled default branch as base unless --base was explicitly provided
+        if not base_branch:
+            base_branch = default_branch
+
     # If label already exists as a branch, reuse it instead of creating one.
     label_branch_exists = operations.branch_exists(label, repo_root)
     remote_label_branch_exists = False
@@ -303,7 +326,9 @@ def start_session(
     _add_session(session_data)
 
     typer.secho(
-        f"Successfully started session '{label}' in {repo_name}.", fg="bright_green", bold=True
+        f"Successfully started session '{label}' in {repo_name}.",
+        fg="bright_green",
+        bold=True,
     )
     typer.echo(f"  Repository: {repo_root}")
     typer.echo(f"  Worktree: {worktree_path}")
@@ -389,7 +414,8 @@ def _remove_workspace_session(session_data: Dict[str, Any]):
             shutil.rmtree(workspace_root)
         except OSError as e:
             typer.secho(
-                f"Warning: Could not remove workspace directory {workspace_root}: {e}", fg="yellow"
+                f"Warning: Could not remove workspace directory {workspace_root}: {e}",
+                fg="yellow",
             )
 
 
@@ -408,10 +434,16 @@ def remove_all_sessions():
         return
 
     # Separate regular sessions from workspaces for display
-    regular_sessions = {k: v for k, v in sessions.items() if v.get("session_type") != "workspace"}
-    workspace_sessions = {k: v for k, v in sessions.items() if v.get("session_type") == "workspace"}
+    regular_sessions = {
+        k: v for k, v in sessions.items() if v.get("session_type") != "workspace"
+    }
+    workspace_sessions = {
+        k: v for k, v in sessions.items() if v.get("session_type") == "workspace"
+    }
 
-    typer.echo(f"This will remove {len(regular_sessions)} sessions and {len(workspace_sessions)} workspaces:")
+    typer.echo(
+        f"This will remove {len(regular_sessions)} sessions and {len(workspace_sessions)} workspaces:"
+    )
     for label in regular_sessions:
         typer.echo(f"  Session: {label}")
     for label in workspace_sessions:
@@ -485,7 +517,9 @@ def list_sessions():
             # Display workspace info
             workspace_repos = data.get("workspace_repos", [])
             repo_names = [repo["repo_name"] for repo in workspace_repos]
-            repo_display = f"workspace ({len(repo_names)} repos: {', '.join(repo_names)})"
+            repo_display = (
+                f"workspace ({len(repo_names)} repos: {', '.join(repo_names)})"
+            )
         else:
             # Display regular session info
             repo_display = f"{data['repository_name']} ({Path(data['repository_path']).parent.name})"
@@ -536,7 +570,9 @@ def open_session(label: str):
     raise typer.Exit(1)
 
 
-def checkout_session(target: str, custom_label: Optional[str] = None, repo_path: Optional[str] = None):
+def checkout_session(
+    target: str, custom_label: Optional[str] = None, repo_path: Optional[str] = None
+):
     """Checkout existing branch or PR into new session."""
     try:
         # Parse target to determine branch name and checkout strategy
@@ -550,7 +586,11 @@ def checkout_session(target: str, custom_label: Optional[str] = None, repo_path:
 
     # Validate label is globally unique
     if not _validate_label_unique(label):
-        typer.secho(f"Error: Label '{label}' already exists. Labels must be globally unique.", fg="red", err=True)
+        typer.secho(
+            f"Error: Label '{label}' already exists. Labels must be globally unique.",
+            fg="red",
+            err=True,
+        )
         raise typer.Exit(1)
 
     # Resolve repository path
@@ -579,9 +619,7 @@ def checkout_session(target: str, custom_label: Optional[str] = None, repo_path:
     config = initialization.load_par_config(repo_root)
     if config:
         initialization.copy_included_files(config, repo_root, worktree_path)
-        initialization.run_initialization(
-            config, session_name, worktree_path
-        )
+        initialization.run_initialization(config, session_name, worktree_path)
 
     # Create session data for global state
     session_data = {
@@ -631,7 +669,7 @@ def open_control_center():
             all_repos.add(f"workspace-{label}")
         else:
             # For regular sessions, use repository name
-            all_repos.add(data['repository_name'])
+            all_repos.add(data["repository_name"])
 
     # Determine if we need to include repo names (more than one unique repo)
     include_repo_name = len(all_repos) > 1
@@ -645,21 +683,19 @@ def open_control_center():
 
         if session_type == "workspace":
             # For workspaces, create single window starting from workspace root
-            workspace_root = data["repository_path"]  # This is the workspace root directory
+            workspace_root = data[
+                "repository_path"
+            ]  # This is the workspace root directory
             name = f"workspace-{label}" if include_repo_name else label
-            active_contexts.append({
-                "name": name,
-                "path": workspace_root,
-                "type": "workspace"
-            })
+            active_contexts.append(
+                {"name": name, "path": workspace_root, "type": "workspace"}
+            )
         else:
             # For regular sessions, create single window
-            repo_name = data['repository_name']
+            repo_name = data["repository_name"]
             name = f"{repo_name}-{label}" if include_repo_name else label
-            active_contexts.append({
-                "name": name,
-                "path": data["worktree_path"],
-                "type": "session"
-            })
+            active_contexts.append(
+                {"name": name, "path": data["worktree_path"], "type": "session"}
+            )
 
     operations.open_control_center(active_contexts)
diff --git a/par/test_start.py b/par/test_start.py
index a3e7d7d..7fb5e35 100644
--- a/par/test_start.py
+++ b/par/test_start.py
@@ -17,6 +17,7 @@ def test_cli_start_forwards_base_branch(mock_start_session):
         path="/tmp/repo",
         base_branch="develop",
         open_session=True,
+        pull_default=False,
     )
 
     mock_start_session.assert_called_once_with(
@@ -24,6 +25,7 @@ def test_cli_start_forwards_base_branch(mock_start_session):
         repo_path="/tmp/repo",
         open_session=True,
         base_branch="develop",
+        pull_default=False,
     )
 
 
@@ -33,7 +35,15 @@ def test_cli_create_alias_forwards_base_branch(mock_start_session):
     runner = CliRunner()
     result = runner.invoke(
         cli.app,
-        ["create", "feature-auth", "--path", "/tmp/repo", "--base", "develop", "--open"],
+        [
+            "create",
+            "feature-auth",
+            "--path",
+            "/tmp/repo",
+            "--base",
+            "develop",
+            "--open",
+        ],
     )
 
     assert result.exit_code == 0
@@ -42,6 +52,45 @@ def test_cli_create_alias_forwards_base_branch(mock_start_session):
         repo_path="/tmp/repo",
         open_session=True,
         base_branch="develop",
+        pull_default=False,
+    )
+
+
+@patch("par.cli.core.start_session")
+def test_cli_start_forwards_pull_default(mock_start_session):
+    """CLI start passes --pull-default through to core.start_session."""
+    runner = CliRunner()
+    result = runner.invoke(
+        cli.app,
+        ["start", "feature-auth", "--path", "/tmp/repo", "--pull-default"],
+    )
+
+    assert result.exit_code == 0
+    mock_start_session.assert_called_once_with(
+        "feature-auth",
+        repo_path="/tmp/repo",
+        open_session=False,
+        base_branch=None,
+        pull_default=True,
+    )
+
+
+@patch("par.cli.core.start_session")
+def test_cli_start_pull_default_off_by_default(mock_start_session):
+    """pull_default defaults to False when flag is not provided."""
+    runner = CliRunner()
+    result = runner.invoke(
+        cli.app,
+        ["start", "feature-auth", "--path", "/tmp/repo"],
+    )
+
+    assert result.exit_code == 0
+    mock_start_session.assert_called_once_with(
+        "feature-auth",
+        repo_path="/tmp/repo",
+        open_session=False,
+        base_branch=None,
+        pull_default=False,
     )
 
 
@@ -81,6 +130,90 @@ def test_start_session_passes_base_branch(
     )
 
 
+@patch("par.core._add_session")
+@patch("par.core.initialization.load_par_config", return_value=None)
+@patch("par.core.operations.create_tmux_session")
+@patch("par.core.operations.create_worktree")
+@patch("par.core.operations.fetch_remote_branch", return_value=False)
+@patch("par.core.operations.branch_exists", return_value=False)
+@patch("par.core.operations.tmux_session_exists", return_value=False)
+@patch("par.core.utils.get_tmux_session_name", return_value="par-repo-1234-feature")
+@patch("par.core.utils.get_worktree_path", return_value=Path("/tmp/worktree"))
+@patch("par.core.utils.resolve_repository_path", return_value=Path("/tmp/repo"))
+@patch("par.core._validate_label_unique", return_value=True)
+@patch("par.core.operations.pull_default_branch")
+@patch("par.core.operations.get_default_branch", return_value="main")
+def test_start_session_pull_default_uses_default_branch_as_base(
+    mock_get_default,
+    mock_pull_default,
+    _mock_label_unique,
+    _mock_resolve_repo,
+    _mock_get_worktree_path,
+    _mock_get_tmux_name,
+    _mock_tmux_exists,
+    _mock_branch_exists,
+    _mock_fetch_remote,
+    mock_create_worktree,
+    _mock_create_tmux,
+    _mock_load_config,
+    _mock_add_session,
+):
+    """With pull_default, start_session pulls default branch and uses it as base."""
+    core.start_session("feature-auth", pull_default=True)
+
+    mock_get_default.assert_called_once_with(Path("/tmp/repo"))
+    mock_pull_default.assert_called_once_with(Path("/tmp/repo"), "main")
+    mock_create_worktree.assert_called_once_with(
+        "feature-auth",
+        Path("/tmp/worktree"),
+        Path("/tmp/repo"),
+        base_branch="main",
+        create_branch=True,
+    )
+
+
+@patch("par.core._add_session")
+@patch("par.core.initialization.load_par_config", return_value=None)
+@patch("par.core.operations.create_tmux_session")
+@patch("par.core.operations.create_worktree")
+@patch("par.core.operations.fetch_remote_branch", return_value=False)
+@patch("par.core.operations.branch_exists", return_value=False)
+@patch("par.core.operations.tmux_session_exists", return_value=False)
+@patch("par.core.utils.get_tmux_session_name", return_value="par-repo-1234-feature")
+@patch("par.core.utils.get_worktree_path", return_value=Path("/tmp/worktree"))
+@patch("par.core.utils.resolve_repository_path", return_value=Path("/tmp/repo"))
+@patch("par.core._validate_label_unique", return_value=True)
+@patch("par.core.operations.pull_default_branch")
+@patch("par.core.operations.get_default_branch", return_value="main")
+def test_start_session_pull_default_with_explicit_base(
+    mock_get_default,
+    mock_pull_default,
+    _mock_label_unique,
+    _mock_resolve_repo,
+    _mock_get_worktree_path,
+    _mock_get_tmux_name,
+    _mock_tmux_exists,
+    _mock_branch_exists,
+    _mock_fetch_remote,
+    mock_create_worktree,
+    _mock_create_tmux,
+    _mock_load_config,
+    _mock_add_session,
+):
+    """With pull_default and explicit --base, --base takes precedence."""
+    core.start_session("feature-auth", base_branch="develop", pull_default=True)
+
+    mock_get_default.assert_called_once_with(Path("/tmp/repo"))
+    mock_pull_default.assert_called_once_with(Path("/tmp/repo"), "main")
+    mock_create_worktree.assert_called_once_with(
+        "feature-auth",
+        Path("/tmp/worktree"),
+        Path("/tmp/repo"),
+        base_branch="develop",
+        create_branch=True,
+    )
+
+
 @patch("par.operations.run_cmd")
 def test_create_worktree_uses_resolved_base_commit(mock_run_cmd):
     """Worktree creation resolves base ref to commit SHA before branching."""