Josh (Just One Single History)

Josh is a platform designed to scale distributed development and collaboration with Git. It addresses the challenges of growing organizations by enabling developers to work in codebases of any size without slowing down change velocity.

Key capabilities include:

• Repo Filtering: Instead of splitting monorepos into multiple static repositories for scalability or access control, Josh uses fast, reversible Git history transformations. This allows you to present any part of a Git repository (e.g., a subfolder) as an independent repository, preserving history and the ability to contribute while limiting visibility, scope, and CI rebuilds.
• Build / CI Integration: Josh provides a GraphQL API to check the state of a repository or its partial projections without performing a full checkout. This allows CI systems to quickly determine if a specific subproject has already been successfully built.

Josh is a tool designed to bridge the gap between monorepos and multirepos by providing a blazingly-fast, incremental, and reversible implementation of git history filtering.

Unlike traditional tools like git-filter-branch (which is slow and intended for one-off fixes) or git-filter-repo/BFG repo cleaner (which are fast but destructive and intended for maintenance), Josh is designed for everyday workflows.

Key technical characteristics:

• Incremental Filtering: Josh uses a persistent cache between runs. The work required to re-run a filter on a new commit is proportional to the changes since the last run, rather than the total length of the history.
• Reversibility: To ensure operations are reversible, Josh does not allow arbitrary scripting. Instead, it uses a Domain-Specific Language (DSL) to express complex filters as combinations of simpler, predictable ones.
• Non-destructive: Because filters are reversible and fast, they can be used seamlessly by developers and CI systems to relate histories between different repositories without discarding the original history.

A View is a named, versioned filter object stored as a git ref. A view is identified by any ref whose commit tree contains a view.josh file.

Views are designed to decouple the filter definition from the repository history, solving several limitations of the legacy workspace mechanism:

• Versioned Policy: Provides a mutable, versioned home for meta options (like history flags, gpgsig handling, or compatibility flags) without requiring changes to the source history.
• Migration Points: Allows recording structural changes (e.g., moving a root directory) at specific points in time using :rev.
• Stable Identity: Unlike legacy workspaces, which vary depending on the branch being fetched, a View provides a consistent identity for use in CI configurations and remote URLs.
• Decoupled Storage: The view stores the view.josh text itself, rather than a serialized filter representation.

Concept: Levels and Namespaces

In josh, Levels are distinct histories related by filters. There is no single 'canonical' history; instead, remotes and worktrees sit at different levels.

To prevent accidental usage of unrelated branches, josh uses Namespaces at the protocol layer. Every level is a git namespace in the store (e.g., refs/namespaces/<level>/...). A worktree only sees the refs belonging to its specific level.

Concept: How history flows between levels

• Same level (e.g., a worktree and a remote at the same level): Use standard git fetch and git push. No filtering occurs.
• One edge apart (e.g., a worktree at a filtered level and a remote at the wider level):
  • josh fetch applies the filter to move history from the wider level to the filtered level.
  • josh push 'unapplies' the filter to move history from the filtered level back to the wider level.

Comparison: josh worktrees vs. git sparse-checkout

The josh CLI uses a 'bare-repo-plus-worktrees' pattern rather than a direct git drop-in replacement model. This design separates the shared object store from the specific filtered views (projections) you work on.

Core Components

• Shared Store: Created via josh init, this is a bare repository that holds the shared object store, cache, and network fetch logic. It does not contain a working checkout.
• Upstreams: Attached to the store using josh remote add.
• Worktrees: Created via josh worktree add, these are filtered checkouts. Each worktree is tied to a specific filter (projection), allowing you to work on different parts of a repository side-by-side.

Key Benefits

• Shared Costs: Unfiltered history is fetched once for all worktrees. Filtering work is cached in a shared sled cache, so multiple worktrees (or multiple agents) do not multiply network or CPU costs.
• Isolation: A worktree is a physical scope boundary. An agent or user cannot touch files outside the worktree's projection.
• Plain Git Compatibility: Inside a worktree, everything is standard git. git fetch and git push operate on the local, filtered history provided by the josh store via git namespaces.