Skip to content

README.md

Latest commit

 

History

History
88 lines (66 loc) · 3.63 KB

README.md

File metadata and controls

88 lines (66 loc) · 3.63 KB

Devspace

CLI tool to create and manage git worktrees in multiple repositories.

Features • Installation • Usage • Roadmap

Features demo

Features

  • Manage worktrees — create, delete, and navigate git worktrees across different repositories.
  • Worktree status indicators — each worktree shows its remote branch state:
    • ✔ remote branch exists (green)
    • ✘ branch merged or deleted remotely (red)
    • ⬆ never pushed to remote
    • * dirty working tree — uncommitted changes
  • Create worktrees from PR links — paste a GitHub PR URL and devspace clones the repo and creates worktree from the PR branch (requires gh CLI or read-only GITHUB_TOKEN).
  • Vi-style navigation

Rationale

It simplifies working in multiple git repositories, and multiple PRs in each repository. Where each PR has a separate git worktree for ease of switching between the PRs.

The idea is to simplify context switching between open PRs by having all the git worktrees visible and manageable in single place.

devspace scans one or more repositories directories (DEVSPACE_REPOS_DIR) for git repos, and stores worktrees under a separate directory (DEVSPACE_WORKTREES_DIR).

.
├── work_repos_dir/           # work git repositories
│   ├── backend-repo/
│   └── frontend-repo/
├── personal_repos_dir/       # personal git repositories
│   └── side-project/
└── worktrees_dir/            # worktrees managed by devspace

Assume, there is a new feature to add a button in the UI, and that button requires a new endpoint in the backend. Worktrees can be created as below:

  • In the frontend-repo, create new wortkree with a branch named add-new-button-to-the-ui.
  • and, in the backend-repo, create new wortkree with a branch named add-backend-api-for-the-new-button.

When these worktrees are created in devspace they will be stored under the worktrees_dir as below:

└── worktrees_dir/
    ├── backend-repo/
    │   └── add-backend-api-for-the-new-button/   # checked-out worktree
    │       ├── src/
    │       └── ...
    └── frontend-repo/
        └── add-new-button-to-the-ui/             # checked-out worktree
            ├── src/
            └── ...

To switch between the worktrees, run cd $(devspace) to go the directory of the selected worktree.

Installation

Download the binary from the releases or clone the repo and inside the root directory run: cargo install --path . --locked

Typicall, the binary will be installed in $HOME/.cargo/bin/devspace.

Usage

Run cd $(devspace) in bash/zsh or cd (devspace) in fish shell from any directory with the below CLI options, or define the environment variables and run it without any CLI option:

  • --repos-dir: one or more directories where repositories are stored, colon-separated (or set DEVSPACE_REPOS_DIR env variable, e.g. /path/a:/path/b). Can be repeated: --repos-dir /a --repos-dir /b
  • --worktrees-dir: the directory where the worktrees will be stored (or set DEVSPACE_WORKTREES_DIR env variable).

Keybindings

devspace uses vi-style keybindings. Check them with ?

Roadmap

  • Create new worktrees.
  • Delete worktrees.
  • Show the status of worktrees (e.g. stale, active ...etc.).
  • Create worktrees from remote branches.
  • Create PRs from worktrees.
  • Add metadata to worktrees, e.g. JIRA links, PR links ...etc.