### Start Nix Shell Environment

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/testing.md

Enter the Nix shell environment, which provides the necessary tools and setup for running integration tests. This command may take a significant amount of time on the first execution.

```shell
nix-shell shell.nix
```

--------------------------------

### Install LFS Test Server using Go

Source: https://github.com/josh-project/josh/blob/master/lfs-test-server/README.md

Installs the LFS Test Server using the Go installer. Ensure Go is set up in your environment.

```bash
go install github.com/git-lfs/lfs-test-server
```

--------------------------------

### Install Josh CLI

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/gettingstarted.md

Install the Josh command-line tool using Cargo. Ensure you have Rust and Cargo installed.

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

--------------------------------

### Install hyper_cgi for Testing

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/testing.md

Install the hyper_cgi tool with the necessary feature for running integration tests. This is a prerequisite for setting up the test environment.

```shell
cargo install hyper_cgi --features=test-server
```

--------------------------------

### Filter Syntax Example

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/filters.md

Demonstrates the basic syntax for filters, including chaining and arguments with quotes.

```plaintext
:filter1:filter2
```

```plaintext
:filter=argument1,"argument2"
```

--------------------------------

### Run josh-proxy with Docker

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/proxy.md

Example of running a josh-proxy instance using Docker, mapping a port, setting the upstream remote, and mounting a volume for data storage.

```bash
docker run -p 8000:8000 -e JOSH_REMOTE=https://github.com -v josh-vol:/data/git joshproject/josh-proxy:latest
```

--------------------------------

### Run the LFS Test Server

Source: https://github.com/josh-project/josh/blob/master/lfs-test-server/README.md

Executes the LFS Test Server binary. If a run script is used, it should be executed. Ensure the binary is built or installed first.

```bash
bash run.sh

```

--------------------------------

### Map Dependency in workspace.josh

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/workspaces.md

Define which folders from the central repository should be mapped into the current workspace and where they should appear. This example maps `library1` to the `modules/lib1` path within the workspace.

```shell
modules/lib1 = :/library1
```

--------------------------------

### Example Commit Message with Change ID

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/stacked-changes.md

An example commit message demonstrating the placement of a change ID in the footer.

```git
Add input validation to the login form

Validates that the email field is non-empty and well-formed before
submission. Returns an error message inline without clearing the form.

Change: login-form-validation
```

--------------------------------

### Starlark Filter Example

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/experimental.md

This Starlark script dynamically includes every top-level subdirectory as a prefixed subtree. It's applied using the `:!st/config` syntax.

```python
# st/config.star
parts = [filter.subdir(d).prefix(d) for d in tree.dirs("")]
filter = compose(parts)
```

--------------------------------

### Josh Dependency Detection Example

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/stacked-changes.md

Illustrates how Josh determines which intermediate commits to include when publishing a change based on overlapping file paths. Commits touching different files are omitted.

```text
[base] ← A (modifies auth/login.rs) ← B (modifies ui/button.rs) ← C (modifies auth/session.rs)
```

--------------------------------

### Run a Specific Josh Workspace

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/josh-run.md

To run tests for a particular workspace, provide its path as a filter. For example, `:+ws/build-rust` targets the build-rust workspace.

```sh
josh compose run . :+ws/build-rust
```

--------------------------------

### Clone repository with custom name via josh-proxy

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/proxy.md

Example of cloning a repository through josh-proxy, specifying a custom name for the local repository after the filter operations.

```bash
git clone http://localhost:8000/josh-project/josh.git:/docs:prefix=josh-docs.git my-repo
```

--------------------------------

### Clone Project1 Workspace via Josh Proxy

Source: https://github.com/josh-project/josh/blob/master/docs/src/usecases.md

Clone a specific workspace ('project1') from a central monorepo using a Josh proxy. This is an alternative to the CLI method, useful for environments with a Josh proxy setup.

```bash
$ git clone http://josh/central.git:workspace=workspaces/project1.git
```

--------------------------------

### Josh Workspace Definition: Cargo Fetch

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/josh-run.md

Example of a Josh workspace definition file (`ws/fetch.josh`) for fetching Cargo dependencies. It utilizes a persistent cache volume and includes only necessary files to ensure cache validity.

```josh
:$label="cargo fetch"
:#image[:+images/dev-local]
:$cache="rust"
:$network="host"

:$cmd="cargo fetch --locked"

worktree = :[
    ::**/Cargo.toml
    ::**/Cargo.lock
    ::**/rust-toolchain.toml
    ::**/lib.rs
    ::**/main.rs
]
```

--------------------------------

### Josh Workspace Definition: Rust Build

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/josh-run.md

Example of a Josh workspace definition file (`ws/build-rust.josh`) for building a Rust project. It declares an input dependency on a fetch workspace, injects environment variables, and specifies necessary files for compilation.

```josh
:$label="rust build"
:#image[:+images/dev-local]
:$cache="rust"

inputs = :[
    :#fetch[:+ws/fetch]
]

env = :[
    ::JOSH_VERSION=VERSION_STRING
]

worktree = :[
    ::run.sh=ws/build-rust.sh
    ::Cargo.toml
    ::Cargo.lock
    ::rust-toolchain.toml
    ::josh-/*
    ::forges/
]
```

--------------------------------

### Run All Tests

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/testing.md

Execute all unit and documentation tests for the entire project.

```shell
cargo test --all
```

--------------------------------

### Build LFS Test Server from Source

Source: https://github.com/josh-project/josh/blob/master/lfs-test-server/README.md

Builds the LFS Test Server from its source code using Go tools. This is useful for development or when pre-compiled binaries are not available.

```bash
go get github.com/git-lfs/lfs-test-server
```

--------------------------------

### Build the LFS Test Server Binary

Source: https://github.com/josh-project/josh/blob/master/lfs-test-server/README.md

Builds the LFS Test Server executable from the source code in the current directory. This command should be run after cloning the repository or downloading the source.

```bash
go build

```

--------------------------------

### Build Project Binaries

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/testing.md

Compile all necessary binaries for the Josh project, including the main binary, the josh-filter binary, and the josh-proxy.

```shell
cargo build
```

```shell
cargo build --bin josh-filter
```

```shell
cargo build --manifest-path josh-proxy/Cargo.toml
```

--------------------------------

### Build Josh Proxy in Profiling Configuration

Source: https://github.com/josh-project/josh/blob/master/josh-proxy/benches/README.md

Build the josh-proxy crate with the 'profiling' profile to enable performance optimizations for benchmarking.

```bash
cargo build -p josh-proxy --profile profiling
```

--------------------------------

### Clone josh documentation via josh-proxy

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/proxy.md

Demonstrates cloning the josh documentation repository through a josh-proxy instance. Note the double '.git' suffix required in the URL.

```bash
git clone http://localhost:8000/josh-project/josh.git:/docs.git
```

--------------------------------

### Map Multiple Dependencies for Application2

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/workspaces.md

Configure `workspace.josh` for `application2` to include multiple dependencies, mapping `library1` and `library2` to `libs/lib1` and `libs/lib2` respectively.

```shell
libs/lib1 = :/library1
libs/lib2 = :/library2
```

--------------------------------

### Run All Tests

Source: https://github.com/josh-project/josh/blob/master/AGENTS.md

Execute all defined tests within the project using the default working tree.

```bash
josh compose run
```

--------------------------------

### Typical Josh Cache Workflow

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

Illustrates a common workflow for using the distributed cache, involving building and pushing the cache on one machine and fetching it on another.

```shell
# On the machine that computes the cache (e.g. CI):
josh cache build
josh cache push

# On another machine (e.g. a developer workstation):
josh cache fetch
# subsequent josh fetch / clone operations use the pre-built cache
```

--------------------------------

### Configure SSH Client for Josh

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/container.md

Add these lines to your `~/.ssh/config` file to enable agent forwarding and public key authentication for your Josh instance.

```bash
Host your-josh-instance.com
    ForwardAgent yes
    PreferredAuthentications publickey
```

--------------------------------

### List All Test Result Files

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/josh-run.md

Export the contents of the `out_<WS_TREE>` volume and list all test result files within the `tests/` directory using `tar`. Replace `<WS_TREE>` with the actual SHA.

```sh
# List all test result files
podman volume export out_<WS_TREE> | tar -tvf - tests/
```

--------------------------------

### Push workspace creation with create option

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/workspace.md

Push the workspace changes to the origin with the 'create' option. This is required when the commit is created on the server side and needs to be based on existing history.

```bash
git push -o create origin master
```

--------------------------------

### Run Integration Tests

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/testing.md

Execute the integration tests located in the tests/ directory. The -v flag enables verbose output.

```shell
sh run-tests.sh -v tests/
```

--------------------------------

### Log in to GitHub Forge

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/forge.md

Use this command to initiate the authentication process for GitHub forge integration. It will provide a URL and a code to authorize josh.

```shell
josh auth login github
```

--------------------------------

### Build Local Josh Cache

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

Applies the configured filter to fetched refs and populates the local distributed cache. Run this before pushing the cache to ensure it's up-to-date.

```shell
josh cache build [remote]
```

--------------------------------

### Run Josh Proxy Benchmark with Samply

Source: https://github.com/josh-project/josh/blob/master/josh-proxy/benches/README.md

Execute the 'push_upstream' benchmark for josh-proxy using cargo-samply. Ensure to replace placeholder directory paths with your actual repository locations and provide the correct path to the compiled josh-proxy binary.

```bash
cargo samply -p josh-proxy --bench push_upstream --profile profiling -- \
  --upstream-dir /path/to/upstream \
  --proxy-dir /path/to/data \
  --local-dir /path/to/local \
  --source-ref refs/heads/main \
  --josh-proxy-path $(readlink -f target/profiling/josh-proxy)
```

--------------------------------

### Print Specific Test File to Stdout

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/josh-run.md

Export the specified volume and extract a particular test file (e.g., `tests/filter/foo.t`) to standard output using `tar`. Replace `<WS_TREE>` with the actual SHA.

```sh
# Print a specific test file to stdout
podman volume export out_<WS_TREE> | tar -xOf - tests/filter/foo.t
```

--------------------------------

### Commit and Sync Application2 Workspace

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/workspaces.md

Commit the `workspace.josh` file for `application2` and then push and pull to update the workspace with the newly mapped libraries.

```shell
git add workspace.josh
git commit -m "Create workspace for application2"
josh push
josh pull
```

--------------------------------

### Workspace Configuration for Project1

Source: https://github.com/josh-project/josh/blob/master/docs/src/usecases.md

Defines dependencies for 'project1' by including specific modules and tools from the central monorepo. This configuration is versioned within the repository.

```josh
dependencies = :/modules:[
    ::tools/
    ::library1/
]
```

--------------------------------

### Fetch Project Repository

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/importing.md

Fetch the master branch of the project repository you intend to import. This sets the FETCH_HEAD reference.

```sh
git fetch $REPO_URL master
```

--------------------------------

### Add Josh Remote for Project Import

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/importing.md

In the project's checkout, add a Git remote pointing to the monorepo's Josh proxy. The path `/tools/project-b.git` specifies the target location within the monorepo and acts as a filter.

```sh
git remote add josh https://git.company.name/monorepo.git:/tools/project-b.git
```

--------------------------------

### Workspace Mapping for Project2

Source: https://github.com/josh-project/josh/blob/master/docs/src/usecases.md

Maps a specific library from the central monorepo to a local path within 'project2'. This allows 'project2' to use 'library1' as if it were a local dependency.

```josh
libs/library1 = :/modules/library1
```

--------------------------------

### Running a Josh Workspace

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/josh-run.md

This command executes a Josh workspace. Ensure your workspace definition file is correctly placed and referenced.

```sh
josh compose run . :+ws/my-workspace
```

--------------------------------

### Configure Extra Options

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/container.md

Set the JOSH_EXTRA_OPTS environment variable to pass extra options directly to the josh-proxy process.

```bash
JOSH_EXTRA_OPTS="--some-option --another-option"
```

--------------------------------

### Clone Second Workspace for Application2

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/workspaces.md

Create a new workspace for `application2`, cloning the monorepo and setting the workspace filter. This allows for independent development on `application2`.

```shell
cd ..
josh clone https://github.com/myorg/monorepo.git :workspace=application2 ./application2
cd application2
```

--------------------------------

### Commit and Sync Workspace Changes

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/workspaces.md

After modifying `workspace.josh`, add, commit, and then push and pull to synchronize the workspace with the central repository, making the mapped dependencies available.

```shell
git add workspace.josh
git commit -m "Map library1 into the application1 workspace"
josh push
josh pull
```

--------------------------------

### Filter Options Syntax

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/filters.md

Shows the syntax for applying options to a filter using the :~(...)[] notation.

```plaintext
:~(option1="value1",option2="value2")[:filter]
```

```plaintext
:~(key1="value1",key2="value2")[:/sub1]
```

--------------------------------

### Clone a new workspace

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/workspace.md

Clone a repository to create a new workspace at a specified path. Git will report an empty repository if the path does not exist.

```bash
git clone http://josh/world.git:workspace=ws/hello.git
```

--------------------------------

### Old :rev filter syntax

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/migration.md

Illustrates the previous syntax for the :rev filter, which used bare SHAs for each entry.

```shell
:rev(sha0:filter0,sha1:filter1,0000000000000000000000000000000000000000:default_filter)
```

--------------------------------

### Clone Project1 Workspace with Josh CLI

Source: https://github.com/josh-project/josh/blob/master/docs/src/usecases.md

Clone a specific workspace ('project1') from a central monorepo using the Josh CLI. This checkout will only contain the files and history relevant to 'project1'.

```bash
$ josh clone https://git.example.com/central.git :workspace=workspaces/project1 ./project1
```

--------------------------------

### Configure HTTP Port

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/container.md

Set the JOSH_HTTP_PORT environment variable to specify the HTTP port the container should listen on. Defaults to 8000.

```bash
JOSH_HTTP_PORT="8000"
```

--------------------------------

### Test Staged Files

Source: https://github.com/josh-project/josh/blob/master/AGENTS.md

Use the '+' ref to test only the files that have been staged using 'git add'.

```bash
josh compose run +
```

--------------------------------

### Docker Run Command with Authentication

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/proxy.md

Use this command to run the Josh proxy in Docker with authentication enabled and restricted to specific repositories. Ensure `JOSH_REMOTE` is set to the desired GitHub organization or repository URL.

```bash
docker run -d -p 8000:8000 -e JOSH_EXTRA_OPTS="--require-auth" -e JOSH_REMOTE=https://github.com/josh-project -v josh-vol:$(pwd)/git_data joshproject/josh-proxy:latest
```

--------------------------------

### Build from Last Commit for Josh Tests

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/josh-run.md

Perform a clean build from the last commit (HEAD) without considering local changes. This is ideal for ensuring consistent builds or for before/after comparisons.

```sh
josh compose run HEAD :+ws/test
```

--------------------------------

### Writing Commits with Change Footers

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/stacked-changes.md

When working on a feature, create individual commits for each logical step. Add a 'Change:' footer to commits intended for review, specifying a unique identifier for the change.

```shell
git commit -m "Add validation for input fields

Change: input-validation"
```

```shell
git commit -m "Wire validation into the form component

Change: form-wiring"
```

```shell
git commit -m "Add tests for form validation

Change: validation-tests"
```

--------------------------------

### Migrating :from filter to :rev

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/migration.md

Shows how to convert a removed :from filter to its equivalent :rev expression using the new syntax.

```shell
:rev(<=sha:/,_:filter)
```

--------------------------------

### LFS Test Server Run Script with HTTPS Configuration

Source: https://github.com/josh-project/josh/blob/master/lfs-test-server/README.md

A bash script to configure and run the LFS Test Server with HTTPS enabled. It sets environment variables for listening address, host, content path, admin credentials, certificate files, and scheme.

```bash
#!/bin/bash

set -eu
set -o pipefail


LFS_LISTEN="tcp://:9999"
LFS_HOST="127.0.0.1:9999"
LFS_CONTENTPATH="content"
LFS_ADMINUSER="<cool admin user name>"
LFS_ADMINPASS="<better admin password>"
LFS_CERT="mine.crt"
LFS_KEY="mine.key"
LFS_SCHEME="https"

export LFS_LISTEN LFS_HOST LFS_CONTENTPATH LFS_ADMINUSER LFS_ADMINPASS LFS_CERT LFS_KEY LFS_SCHEME

./lfs-test-server

```

--------------------------------

### New :rev filter syntax

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/migration.md

Demonstrates the updated :rev filter syntax requiring explicit match operators and using '_' for the default case.

```shell
:rev(<=sha0:filter0,<=sha1:filter1,_:default_filter)
```

--------------------------------

### Use Staged Files for Josh Tests

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/josh-run.md

Build and test using only the staged files in the Git index by prefixing the reference with `+`. This is useful for testing changes that have been explicitly added with `git add`.

```sh
josh compose run + :+ws/test
```

--------------------------------

### Clone Repository with Filter

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

Clone a Git repository, applying a specified filter projection. Use this to download only specific parts of a repository.

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

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

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

--------------------------------

### Test Failure Output Format

Source: https://github.com/josh-project/josh/blob/master/AGENTS.md

For failing tests, the output includes 'FAILED: <name>' followed by the prysk diff format, showing the command, expected output, and actual output.

```text
FAILED: <name>
```

--------------------------------

### Publishing Stacked Changes

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/stacked-changes.md

Use the `josh changes publish` command to push your commits as refs. This command automatically creates or updates pull requests for each commit with a 'Change:' footer, enabling a stacked review process.

```shell
josh changes publish
```

--------------------------------

### Partial Clone with Josh CLI

Source: https://github.com/josh-project/josh/blob/master/docs/src/usecases.md

Clone a specific subdirectory from a monorepo using the Josh CLI. This creates a local repository containing only the specified path and its relevant commit history.

```bash
$ josh clone https://git.example.com/monorepo.git :/path/to/library ./library
```

--------------------------------

### Run a Josh workspace

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

Executes a workspace defined in compose.josh within an isolated container. Supports specifying a Git reference and a workspace filter.

```shell
josh compose run [OPTIONS] [REFERENCE] [FILTER]
```

```shell
# Run the default workspace defined in compose.josh
josh compose run
```

```shell
# Run the test workspace against the working tree
josh compose run . :+ws/test
```

```shell
# Run using only staged changes
josh compose run + :+ws/test
```

--------------------------------

### Match Files or Directories with Glob Pattern

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/filters.md

Matches all files or directories in the input root that match the provided glob pattern.

```git-commit-filter
::X
```

--------------------------------

### Fetch from Remote with Filter Awareness

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

Fetch updates from a remote repository and update local filtered references. This command is filter-aware, similar to 'git fetch'.

```shell
josh fetch [options]
```

--------------------------------

### Fetch and Integrate Changes with josh pull

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

Use `josh pull` to fetch and integrate changes from a remote repository. It functions similarly to `git pull` but is aware of Josh's filtering capabilities.

```bash
josh pull [options]
```

--------------------------------

### Configure HTTP Remote

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/container.md

Set the JOSH_REMOTE environment variable to specify the HTTP remote URL for your container.

```bash
JOSH_REMOTE="https://github.com"
```

--------------------------------

### Configure HTTP retries for josh-proxy

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/proxy.md

Shows how to configure the number of HTTP retries for transient upstream errors using the --http-retry flag. Set to 0 to disable retries.

```bash
josh-proxy --remote https://github.com --local /data/git --http-retry 5
```

--------------------------------

### Josh Command Syntax

Source: https://github.com/josh-project/josh/blob/master/docs/src/contributing/josh-run.md

The general syntax for the `josh compose run` command includes optional arguments for reference and filter. The default reference is the working tree (`.`), and the default filter reads `compose.josh`.

```sh
josh compose run [OPTIONS] [REFERENCE] [FILTER]
```

--------------------------------

### Iterating on Feedback

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/stacked-changes.md

After receiving feedback, amend or rebase your commits while preserving the 'Change:' footers. Re-publishing with `josh changes publish` will update existing pull requests instead of creating new ones.

```shell
git rebase -i HEAD~3   # edit commits, preserve Change: footers
```

```shell
josh changes publish  # re-publish; existing PRs are updated, not recreated
```

--------------------------------

### Add new mapping to workspace.josh

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/workspace.md

Add a new mapping entry to the workspace.josh file to include a shared path in a new location within the workspace. Josh will rewrite the mapping to a canonical format.

```bash
... 
new/mapping/location/in/workspace = :/new/mapping/location/in/monorepo
```

--------------------------------

### Rewrite History with Prefix

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/importing.md

Use `josh-filter` to rewrite the fetched history, prefixing all paths to simulate the project's development within the monorepo's target directory. This sets the FILTERED_HEAD reference.

```sh
josh-filter ':prefix=tools/project-b' FETCH_HEAD
```

--------------------------------

### Ordering with Change-Series Footer

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/stacked-changes.md

Use the `Change-Series:` footer to establish a logical order between commits that touch disjoint file sets. Josh ensures commits with the same series label are published in the specified order.

```git
Add unit tests for the new validation helper

Change: validation-tests
Change-Series: login-validation
```

```git
Add input validation helper

Change: input-validation
Change-Series: login-validation
```

--------------------------------

### Generate SSL Certificate and Key

Source: https://github.com/josh-project/josh/blob/master/lfs-test-server/README.md

Generates a self-signed SSL certificate (mine.crt) and a private key (mine.key) using OpenSSL. These are required for running the LFS Test Server over HTTPS.

```bash
openssl req -x509 -sha256 -nodes -days 2100 -newkey rsa:2048 -keyout mine.key -out mine.crt
```

--------------------------------

### Clone Entire Repository

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/gettingstarted.md

Clone a Git repository without any filter, equivalent to a standard 'git clone'.

```shell
josh clone https://github.com/josh-project/josh.git :/ ./josh
```

--------------------------------

### Pull workspace changes with rebase

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/workspace.md

Fetch the server-side created commit using a rebase. This ensures the local workspace is updated with the latest changes, including populated shared paths.

```bash
git pull --rebase
```

--------------------------------

### Commit workspace changes

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/workspace.md

Add and commit the workspace.josh file to record the path mapping changes. This is a necessary step before pushing.

```bash
git add workspace.josh
git commit -m "add workspace"
```

--------------------------------

### Configure SSH Port

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/container.md

Set the JOSH_SSH_PORT environment variable to specify the SSH port the container should listen on. Defaults to 8022.

```bash
JOSH_SSH_PORT="8022"
```

--------------------------------

### Partial Clone via Josh Proxy

Source: https://github.com/josh-project/josh/blob/master/docs/src/usecases.md

Clone a specific subdirectory from a monorepo using a Josh proxy. This method is useful when direct Git access is not available or when leveraging a centralized Josh service.

```bash
$ git clone http://josh/monorepo.git:/path/to/library.git
```

--------------------------------

### Clone Repository with Filter

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/gettingstarted.md

Clone a specific subdirectory from a Git repository using a filter. The destination path is always required.

```shell
josh clone https://github.com/josh-project/josh.git :/docs ./josh-docs
```

--------------------------------

### Configure SSH Timeout

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/container.md

Set the JOSH_SSH_TIMEOUT environment variable to configure the timeout in seconds for a single request when serving repos over SSH. Defaults to 300.

```bash
JOSH_SSH_TIMEOUT="300"
```

--------------------------------

### Clone Monorepo with Workspace Filter

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/workspaces.md

Clone a monorepo, scoping it to a specific application using the `:workspace=` filter. This creates a local repository containing only the files and history relevant to the specified application.

```shell
josh clone https://github.com/myorg/monorepo.git :workspace=application1 ./application1
cd application1
```

--------------------------------

### Pull Changes

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/gettingstarted.md

Fetch and integrate updates from the upstream repository into your local filtered repository.

```shell
josh pull
```

--------------------------------

### Add path mapping to workspace.josh

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/workspace.md

Add a path mapping to the workspace.josh file to link a shared path to a location within the workspace. This file is located in the root of the workspace.

```bash
cd hello
echo "mod/a = :/shared/a" > workspace.josh
```

--------------------------------

### Test Summary Output Format

Source: https://github.com/josh-project/josh/blob/master/AGENTS.md

The summary of test execution is printed at the end of the 'josh compose run' output, indicating the number of tests run, skipped, and failed.

```text
# Ran N tests, M skipped, K failed.

```

--------------------------------

### Push Project to Josh with Merge Option

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/importing.md

Push the project's history to the Josh remote using the `-o merge` option. This creates a merge commit in the monorepo, integrating the project's history at the specified path.

```sh
git push josh $ref -o merge
```

--------------------------------

### Run Tests for a Specific Commit

Source: https://github.com/josh-project/josh/blob/master/AGENTS.md

Test a specific Git commit instead of the current working tree. Pass the commit SHA or a common ref like 'HEAD' as the first argument.

```bash
josh compose run HEAD
```

--------------------------------

### Apply Dynamic Filters with :hook

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/filters.md

Applies a different filter to each commit dynamically, resolved at runtime from git notes. Each note body must contain a valid Josh filter expression.

```shell
git notes --ref=commits add -m ':/code' -f HEAD~1
git notes --ref=commits add -m ':/code:pin[::app.js]' -f HEAD
josh-filter ':hook=commits'
```

--------------------------------

### Match Directories with Glob Pattern

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/filters.md

Matches all subdirectories in the input root that match the provided glob pattern.

```git-commit-filter
::X/
```

--------------------------------

### Find Workspaces

Source: https://github.com/josh-project/josh/blob/master/docs/src/usecases.md

This query retrieves the paths of all workspace files within the repository at a specified revision.

```APIDOC
## GraphQL API

### Description
This API allows querying Git repository content without requiring a full clone. It's useful for CI/CD systems or web frontends.

### Query

#### Find all workspaces

This query retrieves the paths of all workspace files within the repository at a specified revision.

**Query Example**
```graphql
query {
  rev(at:"refs/heads/master", filter:"::**/workspace.josh") {
    files { path }
  }
}
```

#### Response Example
```json
{
  "data": {
    "rev": {
      "files": [
        { "path": "path/to/workspace.josh" },
        { "path": "another/path/workspace.josh" }
      ]
    }
  }
}
```
```

--------------------------------

### Re-apply filter for a remote

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

Use `josh filter` to re-apply the filter for an existing remote. This is helpful after manually changing filter configurations without fetching.

```shell
josh filter <remote>
```

--------------------------------

### Configure Git LFS Client URL

Source: https://github.com/josh-project/josh/blob/master/lfs-test-server/README.md

Configures the Git LFS client to use the LFS Test Server by setting the 'url' in the repository's .lfsconfig file. This is essential for directing LFS operations to the test server.

```ini
[lfs]
  url = "http://localhost:8080/"

```

--------------------------------

### Rewrite Git history with josh-filter

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

A standalone binary for rewriting Git history using Josh filter specs. It takes a filter spec and an input reference, printing the resulting commit SHA to stdout.

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

```shell
# Filter the working tree and print the resulting SHA
josh-filter :/docs .
```

```shell
# Filter a specific commit SHA
josh-filter :/docs abc1234 --update refs/my/filtered
```

--------------------------------

### Set SSH Command via Environment Variable

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/container.md

Alternatively, use the `GIT_SSH_COMMAND` environment variable to pass SSH options for agent forwarding and public key authentication when cloning a repository.

```bash
GIT_SSH_COMMAND="ssh -o PreferredAuthentications=publickey -o ForwardAgent=yes" git clone ssh://git@your-josh-instance.internal/...
```

--------------------------------

### Configure HTTP Retries

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/container.md

Set the JOSH_HTTP_RETRY environment variable to configure the number of retries for transient upstream errors with exponential backoff. The default is 3 retries. Set to "0" to disable retries.

```bash
JOSH_HTTP_RETRY="5"
```

--------------------------------

### Configure SSH Remote

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/container.md

Set the JOSH_REMOTE_SSH environment variable to specify the SSH remote URL for your container.

```bash
JOSH_REMOTE_SSH="ssh://git@github.com"
```

--------------------------------

### Fetch Remote Josh Cache

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

Fetches the distributed cache and filtered refs from the remote, warming the local cache without re-computing filters. This is useful for local development after the cache has been built and pushed by another machine.

```shell
josh cache fetch [remote]
```

--------------------------------

### josh clone

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

Clones a repository, optionally applying a filter projection. This command allows you to fetch specific parts of a repository based on a filter specification.

```APIDOC
## josh clone

### Description
Clones a repository, optionally applying a filter projection. This command allows you to fetch specific parts of a repository based on a filter specification.

### Usage
`josh clone <url> <filter> <out> [options]`

### Arguments
- **`<url>`** (string) - Required - Remote repository URL (HTTPS, SSH, or local path)
- **`<filter>`** (string) - Required - Filter spec (e.g. `:/docs`, `:workspace=workspaces/myproject`)
- **`<out>`** (string) - Required - Local directory to clone into

### Options
- **`-b`, `--branch <ref>`** (string) - Optional - Branch or ref to clone (default: `HEAD`)
- **`--forge <name>`** (string) - Optional - Forge integration to use (e.g. `github`)
- **`--no-forge`** - Optional - Disable forge integration

### Examples
```shell
# 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
```
```

--------------------------------

### Query Workspaces with GraphQL API

Source: https://github.com/josh-project/josh/blob/master/docs/src/usecases.md

Use the Josh GraphQL API to find all workspaces present in the tree at a specific revision. This is useful for CI/CD systems or web frontends.

```graphql
query {
  rev(at:"refs/heads/master", filter:"::/ ** /workspace.josh") {
    files { path }
  }
}
```

--------------------------------

### Push Changes from Filtered Repository

Source: https://github.com/josh-project/josh/blob/master/docs/src/guide/gettingstarted.md

After making and committing changes in a filtered repository, use 'josh push' to send them upstream. Josh handles reversing the filter.

```shell
cd josh-docs
# ... edit files, git add, git commit ...
josh push
```

--------------------------------

### Clone a Subfolder as a Git Repository

Source: https://github.com/josh-project/josh/blob/master/README.md

Use this command to clone a specific subfolder of a monorepo as an independent Git repository. This is useful for isolating projects or components within a larger codebase.

```bash
git clone https://git.josh-project.dev/josh.git:/docs.git
```

--------------------------------

### josh fetch

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

Fetches from a remote and updates the filtered local refs. This is a filter-aware equivalent of `git fetch`.

```APIDOC
## josh fetch

### Description
Fetches from a remote and updates the filtered local refs. This is a filter-aware equivalent of `git fetch`.

### Usage
`josh fetch [options]`

### Options
- **`-r`, `--remote <name>`** (string) - Optional - Remote name or URL to fetch from (default: `origin`)
- **`-R`, `--ref <ref>`** (string) - Optional - Ref to fetch (default: `HEAD`)
```

--------------------------------

### Insert Literal File Content

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/experimental.md

Inserts a new file with literal text content at a specified path. No newline is automatically appended. Paths with spaces or special characters must be quoted.

```bash
# Insert a file named "VERSION" containing "1.0" at the root
:$VERSION="1.0"
```

```bash
# Insert a file whose name contains a space
:$'release notes.txt'="Initial release"
```

```bash
# Combine with a subdirectory filter to insert the file alongside existing content
:[:/sub1,:$added.txt="hello world"]
```

--------------------------------

### History Option: Linear

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/filters.md

Applies the 'linear' history option to produce a linear commit history by converting merge commits.

```plaintext
:~(history="linear")[:/sub1]
```

--------------------------------

### Capture Tree ID with Filter

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/experimental.md

Applies a `filter` to the current tree and writes the SHA-1 hash of the resulting tree into a text file at `path`. The filter itself is not included in the output.

```bash
:#version.txt[:/sub1]
```

--------------------------------

### Configure Git LFS Client for HTTPS

Source: https://github.com/josh-project/josh/blob/master/lfs-test-server/README.md

Configures the Git LFS client to use HTTPS with the LFS Test Server. It also shows how to disable SSL certificate verification if using a self-signed certificate.

```ini
[lfs]
  url = "https://localhost:8080/"

[http]
  sslverify = false

```

--------------------------------

### Push Local Josh Cache to Remote

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/cli.md

Pushes the local distributed cache and filtered refs to the backing remote. This allows other machines to fetch the cache.

```shell
josh cache push [remote]
```

--------------------------------

### Gpgsig Option: Normalize LF

Source: https://github.com/josh-project/josh/blob/master/docs/src/reference/filters.md

Applies the 'norm-lf' gpgsig option to normalize \r\n line endings to \n within the gpgsig header.

```plaintext
:~(gpgsig="norm-lf")[:/sub1]
```