### Start Nix Shell Environment

Source: https://josh-project.github.io/josh/contributing/testing.html

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

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

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

### Install Josh CLI

Source: https://josh-project.github.io/josh/reference/cli.html

Instructions on how to install the Josh CLI using cargo.

```APIDOC
## Install Josh CLI

Press `←` or `→` to navigate between chapters
Press `S` or `/` to search in the book
Press `?` to show this help
Press `Esc` to hide this help
# Just One Single History


The `josh` command is the primary tool for working with filtered git repositories. It provides projection-aware equivalents of the common git operations.
## 
```
__
cargo install josh-cli --locked --git https://github.com/josh-project/josh.git
```
```

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

### Install Josh CLI

Source: https://josh-project.github.io/josh/guide/gettingstarted.html

Install the Josh CLI using Cargo. This command requires Rust to be installed.

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

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

### Example: Add Backend Remote

Source: https://josh-project.github.io/josh/print.html

This example demonstrates adding a remote named 'backend' that is scoped to the 'services/backend' subdirectory of a monorepo.

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

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

### Install Josh CLI

Source: https://josh-project.github.io/josh/print.html

Install the Josh CLI tool using cargo, specifying the locked version and the Git repository.

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

```

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

### Install Hyper CGI for Testing

Source: https://josh-project.github.io/josh/contributing/testing.html

Install the hyper_cgi tool with the 'test-server' feature, which is required for certain integration tests. This command may take some time to complete.

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

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

### Workspace Josh File Example

Source: https://josh-project.github.io/josh/print.html

Example of a workspace.josh file defining dependencies. It maps external repository paths to local directories within the workspace.

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

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

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

### Filter with Options and Subdirectory Filter

Source: https://josh-project.github.io/josh/print.html

An example of applying filter options along with a subdirectory filter. This applies the ':/sub1' filter with specified metadata options.

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

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

### Add Path Mapping to workspace.josh

Source: https://josh-project.github.io/josh/print.html

After cloning, navigate to the workspace directory and add path mappings to the workspace.josh file. This example maps 'mod/a' to ':/shared/a'.

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

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

### Define Dependencies in workspace.josh

Source: https://josh-project.github.io/josh/usecases.html

Example of a workspace.josh file defining dependencies for a project. It specifies modules and tools required by the project.

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

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

### Define Workspace Dependencies

Source: https://josh-project.github.io/josh/guide/workspaces.html

Create a `workspace.josh` file to map folders from the central repository into the current workspace. This example maps `library1` to the `modules/lib1` path.

```bash
modules/lib1 = :/library1
```

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

### Scope Filter Example

Source: https://josh-project.github.io/josh/reference/filters.html

Applies a composition filter within a specific scope and then restores the original structure. This example selects `file1` and `file2` within the `sub1` subdirectory.

```shell
:<:/sub1>[::file1,::file2]
```

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

### Run All Cargo Tests

Source: https://josh-project.github.io/josh/contributing/testing.html

Execute all integration tests for the Josh project using Cargo. Ensure you have the necessary environment setup.

```bash
cargo test --all
```

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

### Query Workspaces using Josh GraphQL API

Source: https://josh-project.github.io/josh/usecases.html

Access repository content without cloning using Josh's GraphQL API. This example queries for all workspace.josh files in the repository.

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

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

### Blob Insertion Examples

Source: https://josh-project.github.io/josh/reference/experimental.html

Use `:$path="content"` to insert a new file with literal text content. The path can be quoted if it contains spaces or special characters. Combine with subdirectory filters to place files alongside existing content.

```shell
:$VERSION="1.0"
```

```shell
:$"release notes.txt"="Initial release"
```

```shell
:[:/sub1,:$added.txt="hello world"]
```

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

### Map Libraries in workspace.josh

Source: https://josh-project.github.io/josh/usecases.html

Example of a workspace.josh file mapping libraries from the central monorepo to a project's local hierarchy. This allows projects to depend on shared libraries.

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

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

### Apply Per-Commit Filters Using Git Notes and :hook

Source: https://josh-project.github.io/josh/reference/filters.html

Apply different filters to individual commits dynamically using the :hook argument, which reads filter specifications from git notes. This example demonstrates setting notes and then applying the hook filter.

```bash
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'
```

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

### Log in to GitHub with Josh

Source: https://josh-project.github.io/josh/reference/forge.html

Use this command to initiate the GitHub authentication process for Josh. It will provide a URL and a code to authorize the application in your browser.

```bash
josh auth login github
```

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

### Invert Composition of Filters

Source: https://josh-project.github.io/josh/reference/filters.html

Inverts the composition of multiple filters. This example inverts the combined effect of `:/sub1` and `:/sub2`.

```shell
:invert[:/sub1,:/sub2]
```

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

### Build Project Binaries

Source: https://josh-project.github.io/josh/contributing/testing.html

Compile the main Josh project and specific binaries like 'josh-filter' and 'josh-proxy'. This step is necessary before running tests that depend on these components.

```bash
cargo build
```

```bash
cargo build --bin josh-filter
```

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

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

### Clone Josh Documentation via Proxy

Source: https://josh-project.github.io/josh/reference/proxy.html

Clone the Josh documentation repository through the local josh-proxy instance. Ensure the URL includes the '.git' suffix twice for correct filtering.

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

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

### Typical Josh Cache Workflow

Source: https://josh-project.github.io/josh/reference/cli.html

Demonstrates a common workflow for using the distributed cache, involving building and pushing the cache on one machine (e.g., CI) and fetching it on another (e.g., developer workstation).

```bash
# 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
```

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

### Clone Monorepo for Application 2

Source: https://josh-project.github.io/josh/guide/workspaces.html

Clone the monorepo again, this time scoping it to `application2` and placing it in a new directory. Navigate into the new workspace directory.

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

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

### Map Multiple Dependencies for Application 2

Source: https://josh-project.github.io/josh/guide/workspaces.html

Configure `workspace.josh` for `application2` to map both `library1` and `library2` into the workspace under `libs/lib1` and `libs/lib2` respectively.

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

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

### josh publish

Source: https://josh-project.github.io/josh/reference/cli.html

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.

```APIDOC
## 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]
```

### Parameters
#### Path Parameters
- **remote** (string) - Optional - Remote name to push to (default: `origin`)
- **refspecs** (string) - Optional - Refs to push (default: current branch)

#### Options
- **-f, --force** - Optional - Force-push (non-fast-forward)
- **--atomic** - Optional - Atomic push (all-or-nothing)
- **--dry-run** - Optional - Show what would be pushed without actually pushing
```

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

### Publish Stacked Changes

Source: https://josh-project.github.io/josh/print.html

Pushes each commit as an independent, minimal diff using a 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.

```APIDOC
## POST /api/publish

### Description
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.

### Method
POST

### Endpoint
josh publish [<remote>] [<refspecs>...]

### Parameters
#### Path Parameters
- **remote** (string) - Optional - Remote name to push to (default: `origin`)
- **refspecs** (string) - Optional - Refs to push (default: current branch)

#### Query Parameters
- **force** (boolean) - Optional - Force-push (non-fast-forward)
- **atomic** (boolean) - Optional - Atomic push (all-or-nothing)
- **dry-run** (boolean) - Optional - Show what would be pushed without actually pushing
```

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

### Configure Josh Proxy with Authentication

Source: https://josh-project.github.io/josh/reference/proxy.html

Use JOSH_EXTRA_OPTS to pass the --require-auth flag to josh-proxy when using the Docker image. This ensures authentication prompts for fetching.

```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 
```

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

### Commit Changes with Change ID

Source: https://josh-project.github.io/josh/guide/stacked-changes.html

When working on a feature, create separate commits for each logical step and include a 'Change:' footer in each. Commits without this footer are pushed to the base branch but do not get their own ref or PR.

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

Change: input-validation"
```

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

Change: form-wiring"
```

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

Change: validation-tests"
```

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

### Configure SSH Client for Josh Instance

Source: https://josh-project.github.io/josh/reference/container.html

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

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

```

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

### Commit and Sync Application 2 Workspace

Source: https://josh-project.github.io/josh/guide/workspaces.html

Add the updated `workspace.josh` file, commit the changes, and then push and pull to synchronize the workspace with the mapped libraries.

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

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

### Filter Options Syntax

Source: https://josh-project.github.io/josh/print.html

Illustrates the syntax for applying filter options using the :~(...)[] notation. Options are key-value pairs within parentheses, followed by the filter in square brackets.

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

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

### Run Test Suite

Source: https://josh-project.github.io/josh/contributing/testing.html

Execute the test suite for the Josh project, excluding tests in the 'experimental' directory. Ensure all non-experimental tests pass.

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

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

### Match Files or Directories with Glob

Source: https://josh-project.github.io/josh/reference/filters.html

Matches all files or directories in the input root that conform to the provided glob pattern. Wildcards cannot be consecutive.

```josh
::X
```

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

### Clone Repository with Prefix Filter and Default Naming

Source: https://josh-project.github.io/josh/print.html

Clones the Josh documentation with a prefix filter, but the repository name is still determined by the filter itself ('josh-docs.git'), leading to a nested directory structure.

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

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

### Clone a new workspace

Source: https://josh-project.github.io/josh/reference/workspace.html

Use this command to create a new workspace in a specified path by cloning a repository. Git will report if the path does not exist.

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

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

### Add workspace path mapping

Source: https://josh-project.github.io/josh/reference/workspace.html

After cloning, navigate to the workspace directory and add a path mapping to the workspace.josh file. This maps a local path to a shared repository path.

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

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

### Run Josh Proxy with Docker

Source: https://josh-project.github.io/josh/reference/proxy.html

Deploy a shared caching proxy for Git operations using Docker. This command sets up the proxy for github.com and maps port 8000.

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

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

### Add and Commit Workspace File

Source: https://josh-project.github.io/josh/guide/workspaces.html

Stage and commit the `workspace.josh` file using Git. This records the workspace configuration.

```bash
git add workspace.josh
git commit -m "Map library1 into the application1 workspace"
```

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

### Apply Workspace Filter

Source: https://josh-project.github.io/josh/reference/filters.html

Selects a workspace directory and applies a filter from 'workspace.josh' within that directory. Equivalent to combining a directory selection with a stored filter.

```josh
:workspace=a
```

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

### Filter with Prefix First (Empty Result)

Source: https://josh-project.github.io/josh/reference/filters.html

Applying the prefix filter first results in an empty branch because the entire history is already within the 'josh-docs' directory.

```bash
$ josh-filter :prefix=josh-docs:/docs
```

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

### Clone Project Workspace with Josh CLI

Source: https://josh-project.github.io/josh/usecases.html

Use the josh CLI to clone a specific project workspace from a monorepo. This allows multiple projects to coexist in a single repository and manage dependencies efficiently.

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

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

### Josh Filter: Prefix and Subdirectory Order

Source: https://josh-project.github.io/josh/print.html

Demonstrates how the order of filters affects the output. A prefix filter applied before a subdirectory filter can lead to unexpected results if not carefully constructed.

```bash
$ josh-filter :/docs:prefix=josh-docs
```

```bash
$ josh-filter :prefix=josh-docs:/docs
```

```bash
$ josh-filter :prefix=josh-docs:/josh-docs/docs
```

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

### Fetch External Repository

Source: https://josh-project.github.io/josh/guide/importing.html

Fetches the contents of an external Git repository. This command sets the `FETCH_HEAD` reference to the fetched repository, preparing it for further processing.

```bash
git fetch $REPO_URL master
```

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

### Clone Repository using GIT_SSH_COMMAND

Source: https://josh-project.github.io/josh/print.html

Alternatively, pass SSH client options via GIT_SSH_COMMAND to enable SSH agent forwarding for cloning repositories.

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

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

### Updating Stacked Changes via Rebase and Publish

Source: https://josh-project.github.io/josh/print.html

After receiving feedback, amend or rebase your local commits while preserving the `Change:` footers. Running `josh publish` again will update the existing PRs instead of creating new ones, ensuring continuity.

```bash
__
git rebase -i HEAD~3   # edit commits, preserve Change: footers
josh publish           # re-publish; existing PRs are updated, not recreated
```

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

### josh-filter Options

Source: https://josh-project.github.io/josh/reference/cli.html

Provides a list of available options for the `josh-filter` command, including specifying the update ref, reading filters from a file, squashing commits, and various modes like discovery, tracing, and cache management.

```bash
--update <ref>
--file <path>
--squash-pattern <pattern>
--squash-file <path>
--single
-d
-t
-p
-i
-s
-n
--distributed-cache
--reverse
--check-roundtrip
```

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

### Clone Monorepo with Workspace Filter

Source: https://josh-project.github.io/josh/guide/workspaces.html

Clone a monorepo scoped to a specific application using the `:workspace=` filter. Navigate into the cloned directory afterward.

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

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

### Clone Repository with Filter

Source: https://josh-project.github.io/josh/print.html

Clone a repository, applying a specified filter projection. This command is filter-aware and allows cloning specific subdirectories or workspace projections.

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

```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

```

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

### Fetch from Remote with Josh

Source: https://josh-project.github.io/josh/print.html

Fetch changes from a remote repository and update local references, similar to `git fetch` but filter-aware. Supports specifying remote and ref.

```shell
josh fetch [options]

```

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

### Fetch from Remote

Source: https://josh-project.github.io/josh/reference/cli.html

Fetch changes from a remote repository and update local filtered references. This is a filter-aware equivalent of 'git fetch'.

```bash
josh fetch [options]
```

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

### Josh Filter Options Syntax

Source: https://josh-project.github.io/josh/reference/filters.html

The `:~(...)[]` syntax is used to provide filter options (metadata) that influence how a filter is applied. Options are key-value pairs within parentheses, followed by the filter in square brackets. Multiple options are comma-separated, and values must be double-quoted.

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

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

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

### Apply Multiple Text Replacements

Source: https://josh-project.github.io/josh/print.html

Applies a series of regular expression replacements to all files in the input tree. Each key-value pair defines a regex and its replacement.

```josh
:replace("regex_0":"replacement_0","regex_N":"replacement_N")
```

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

### Match Directories with Glob

Source: https://josh-project.github.io/josh/reference/filters.html

Matches all subdirectories in the input root that conform to the provided glob pattern. Wildcards cannot be consecutive.

```josh
::X/
```

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

### Build Distributed Filter Cache

Source: https://josh-project.github.io/josh/reference/cli.html

Populates the local distributed cache with filter results for all fetched refs. Run this before `josh cache push` to ensure the cache is up-to-date. Accepts an optional remote name, defaulting to 'origin'.

```bash
josh cache build [remote]
```

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

### Commit and Sync Workspace Changes

Source: https://josh-project.github.io/josh/print.html

After defining workspace mappings, add the `workspace.josh` file to Git, commit the changes, and then use `josh push` and `josh pull` to synchronize the workspace with the central repository.

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

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

### Interactive GraphQL Shell

Source: https://josh-project.github.io/josh/reference/graphql.html

Access this URL to use the interactive GraphQL shell for exploring the API and its documentation.

```http
http://hostname/~/graphiql/name_of_repo.git
```

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

### Clone Project Workspace via Josh Proxy

Source: https://josh-project.github.io/josh/usecases.html

Clone a specific project workspace from a monorepo using a shared josh-proxy. Each subproject can define its own workspace.josh file for mapping and dependency management.

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

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

### Clone a Full Repository

Source: https://josh-project.github.io/josh/guide/gettingstarted.html

Clone an entire Git repository without any filters, similar to a standard 'git clone' command.

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

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

### Publish Stacked Changes

Source: https://josh-project.github.io/josh/guide/stacked-changes.html

Use the `josh publish` command to push each qualifying commit as a separate ref. With forge integration, this automatically creates or updates pull requests for each change.

```bash
josh publish
```

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

### Apply Text Replacement

Source: https://josh-project.github.io/josh/reference/filters.html

Applies a series of regular expression replacements to all files in the input tree. Each key-value pair in the object represents a regex and its replacement.

```josh
:replace("regex_0":"replacement_0",...,"regex_N":"replacement_N")
```

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

### Object Reference

Source: https://josh-project.github.io/josh/reference/experimental.html

Use `:&path` to read the git object at `path` and replace its content with a text blob containing the object's SHA-1 hash. If `path` does not exist, the filter is a no-op.

```shell
:&sub1
```

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

### Josh Proxy Instance URL

Source: https://josh-project.github.io/josh/print.html

This is the URL of a josh-proxy instance.

```text
http://localhost:8000
```

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

### Pull Updates with Josh

Source: https://josh-project.github.io/josh/guide/gettingstarted.html

Fetch and integrate updates from the upstream repository into your local Josh-cloned repository.

```bash
josh pull
```

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

### Add Josh Remote for Project Import

Source: https://josh-project.github.io/josh/guide/importing.html

Adds a Git remote pointing to a `josh-proxy` instance, specifying the target path within the monorepo where the project will be imported. The `.git` suffix on the path is important.

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

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

### Tree ID Capture

Source: https://josh-project.github.io/josh/reference/experimental.html

Use `:#path[filter]` to apply a `filter` to the current tree and write the SHA-1 hash of the resulting tree as a text file at `path`. The filter itself does not appear in the output.

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

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

### Clone Repository with Filter

Source: https://josh-project.github.io/josh/reference/cli.html

Clone a Git repository and apply a filter projection to limit the cloned content. Specify the URL, filter, and output directory.

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

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

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

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

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

### Object Dereference

Source: https://josh-project.github.io/josh/reference/experimental.html

Use `:*path` to read a SHA-1 hash from the file at `path` and replace that file with the git object the hash points to. If `path` does not exist or its content is not a valid SHA, an error is returned.

```shell
:*sub1
```

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

### Sync Workspace Changes

Source: https://josh-project.github.io/josh/guide/workspaces.html

Use Josh to push and pull changes, synchronizing the workspace with the central repository and mapped modules.

```bash
josh push
josh pull
```

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

### Add New Mapping to workspace.josh

Source: https://josh-project.github.io/josh/print.html

Add a new mapping entry to the workspace.josh file for a new location in the workspace. Josh will rewrite the entry into a canonical format.

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

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

### Clone Repository with Custom Name

Source: https://josh-project.github.io/josh/reference/proxy.html

Clone a repository through the josh-proxy and explicitly specify the local directory name for the new repository. This overrides the default naming convention based on the URL.

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

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

### Push Project Merge to Josh Proxy

Source: https://josh-project.github.io/josh/guide/importing.html

Pushes the local project's history to the `josh-proxy` with the `-o merge` option. This creates a merge commit in the monorepo, integrating the project's history at the specified location while preserving its original commit hashes.

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

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

### Filter Docs with Prefix

Source: https://josh-project.github.io/josh/reference/filters.html

This command filters out documentation with the prefix 'josh-docs' and stores it in a ref named 'FILTERED_HEAD'.

```bash
$ josh-filter :/docs:prefix=josh-docs
```

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

### Dynamic Subdirectory Inclusion with Prefix

Source: https://josh-project.github.io/josh/reference/experimental.html

This Starlark script dynamically includes every top-level subdirectory as a prefixed subtree. It iterates through directories in the 'tree' and applies a 'subdir' and 'prefix' filter to each.

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

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

### Clone Monorepo Subdirectory with Josh CLI

Source: https://josh-project.github.io/josh/usecases.html

Use the josh CLI to clone a specific subdirectory of a monorepo, treating it as an individual repository. This reduces the scope and size of the clone.

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

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

### Starlark Filter Syntax

Source: https://josh-project.github.io/josh/print.html

Explains the syntax and usage of the Starlark filter, including context filters and script execution.

```APIDOC
## Starlark filter :!path/to/script[context filter]

### Description
Evaluates a Starlark script stored in the repository and uses the filter it produces. The script file is loaded from `path` with a `.star` extension appended automatically.
The optional `[context filter]` scopes the tree that is visible to the script: the context filter is applied to the input tree first, and the result is what the script sees as `tree`. The context filter does not affect the filter that the script returns — it only controls what the script can read.
The script file itself is always included in the output tree alongside whatever the script’s filter selects.

### Script contract
The script must assign a `Filter` value to the variable named `filter`. At the start of execution `filter` is pre-set to a no-op filter, so a minimal script that selects nothing can simply leave it unchanged, or assign a new value:

```starlark
filter = filter.subdir("src")
```

### Global variables available in the script
Variable| Type| Description  
---|---|---
`filter`| `Filter`| Starts as a no-op filter. Assign your result here.  
`tree`| `Tree`| The commit tree (or the context-filtered tree if a context filter was given).  

### Global functions
Function| Description  
---|---
`compose([f1, f2, ...])`| Overlay multiple filters, same semantics as `:[f1,f2,...]`.  

### `Filter` methods
All methods return a new `Filter` and can be chained.
Method| Description  
---|---
`filter.subdir(path)`| Select a subdirectory and make it the root.  
`filter.prefix(path)`| Place the tree under a subdirectory prefix.  
`filter.file(path)`| Select a single file, keeping its path.  
`filter.rename(dst, src)`| Select `src` and place it at `dst`.  
`filter.pattern(pattern)`| Select files/directories matching a glob pattern (`*` allowed).  
`filter.chain(other)`| Apply `other` after this filter.  
`filter.nop()`| No-op; passes the tree through unchanged.  
`filter.empty()`| Produce an empty tree.  
`filter.linear()`| Linearise history (drop merge parents).  
`filter.workspace(path)`| Apply the workspace filter rooted at `path`.  
`filter.stored(path)`| Apply the stored filter at `path.josh`.  
`filter.starlark(path, context_filter)`| Apply another Starlark filter with an optional context filter.  
`filter.author(name, email)`| Override the commit author.  
`filter.committer(name, email)`| Override the committer.  
`filter.message(template)`| Rewrite commit messages using a template.  
`filter.unsign()`| Strip GPG signatures from commits.  
`filter.prune_trivial_merge()`| Remove merge commits whose tree equals their first parent.  
`filter.hook(hook)`| Apply a hook filter.  
`filter.with_meta(key, value)`| Attach metadata to the filter.  
`filter.is_nop()`| Returns `True` if the filter is a no-op.  
`filter.peel()`| Strip metadata from the filter.  

### `Tree` methods
The `tree` object provides read-only access to the commit tree visible to the script.
Method| Description  
---|---
`tree.file(path)`| Returns the text content of the file at `path`, or an empty string if absent or binary.  
`tree.files(path)`| Returns a list of file paths that are direct children of `path`.  
`tree.dirs(path)`| Returns a list of directory paths that are direct children of `path`.  
`tree.tree(path)`| Returns a `Tree` object rooted at `path`.  

### Example
A script that dynamically includes every top-level subdirectory as a prefixed subtree:

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

Applied with `:!st/config`.
```

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

### Fix Bug in Mapped Library and Push

Source: https://josh-project.github.io/josh/guide/workspaces.html

Edit a file within a mapped library in your workspace. Commit the changes using Git and then push them with Josh. Josh will write the change directly to the central repository's library.

```bash
# edit libs/lib1/lib1.h
git commit -a -m "Fix bug in lib1"
josh push
```