josh CLI

The josh command is the primary tool for working with filtered git repositories. It provides projection-aware equivalents of the common git operations.

Installation

cargo install josh-cli --locked --git https://github.com/josh-project/josh.git

josh clone

Clone a repository, optionally applying a filter projection.

josh clone <url> <filter> <out> [options]

Options:

Examples:

# Clone only the docs/ subdirectory
josh clone https://github.com/josh-project/josh.git :/docs ./josh-docs

# Clone a workspace projection
josh clone https://github.com/myorg/monorepo.git :workspace=workspaces/frontend ./frontend

# Clone the full repository (no filter)
josh clone https://github.com/josh-project/josh.git :/ ./josh

josh fetch

Fetch from a remote and update the filtered local refs. Equivalent to git fetch but filter-aware.

josh fetch [options]

Options:

josh pull

Fetch and integrate changes from a remote. Equivalent to git pull but filter-aware.

josh pull [options]

Options:

josh push

Push commits back to the upstream repository. Josh reverses the filter and reconstructs the correct upstream commits, so your changes land in the right place in the monorepo.

josh push [<remote>] [<refspecs>...] [options]

Options:

josh publish

Push each commit as an independent, minimal diff (stacked changes workflow). Each commit with a Change ID is pushed to its own ref and, when forge integration is configured, gets its own pull request.

josh publish [<remote>] [<refspecs>...] [options]

Options:

josh remote

Manage josh-aware remotes.

Note: josh remote add can be used in any existing git repository, not only ones originally cloned with josh clone. This is the standard way to add josh filtering to a repository you already have checked out.

josh remote add

Add a remote with an associated filter projection.

josh remote add <name> <url> <filter> [options]

Options:

Example:

# Add a second remote scoped to the backend/ subdirectory
josh remote add backend https://github.com/myorg/monorepo.git :/services/backend

josh filter

Re-apply the filter for an existing remote to update the local filtered refs. Useful after manually modifying the filter configuration without fetching.

josh filter <remote>

josh auth

Manage authentication credentials for forge integrations. Forge integration is optional and used for automatic pull request management — see Forge integration for details.

josh auth login <forge>
josh auth logout <forge>

The only currently supported forge is github. See Forge integration for full documentation.

josh-filter (standalone binary)

josh-filter is a lower-level command that rewrites git history using Josh filter specs. It is intended for scripting and one-off history rewriting tasks rather than day-to-day development workflows.

By default it reads from HEAD and writes the filtered result to FILTERED_HEAD.

Basic usage:

# Filter HEAD through :/docs and write result to FILTERED_HEAD
josh-filter :/docs

Options: