# ⛏️ Pick

Pick is a utility that processes files based on pattern matching rules.


## Usage
- `pick manifest.toml` to run a task
- `pick --help` for documentation
- `pick gen manifest.toml` generate a sample manifest

A detailed manifest specification is below.


# Writing manifests

A pick manifest is a TOML file with three main sections:

- `config`: Global configuration settings
- `tool`: Tool configuration
- `rules`: Patterns that tell us which files to process

See [`sample.toml`](./sample.toml) for an example configuration.


## Selector Pattern Syntax

Pick uses patterns to select files to process.

- Patterns match against the full file path relative to the source directory
- The first matching rule is applied to each file. Once a rule matches, all others are ignored.
- Patterns are matched in the order they are defined.
- Leading and trailing slashes are ignored
- Multiple consecutive slashes are treated as a single slash


### Wildcards

- `*`: Matches exactly one path segment (one directory or filename component)
- `**`: Matches zero or more path segments (can span across multiple directories)

### Pattern Rules


### Syntax Examples

| Pattern | Description | Matches | Doesn't Match |
|---------|-------------|---------|---------------|
| `file.txt` | Exact file match | `file.txt` | `other.txt`, `dir/file.txt` |
| `dir/file.txt` | Exact path match | `dir/file.txt` | `file.txt`, `other/file.txt` |
| `*.txt` | Any file with .txt extension in root | `file.txt`, `other.txt` | `file.jpg`, `dir/file.txt` |
| `**/*.txt` | Any .txt file anywhere | `file.txt`, `dir/file.txt`, `a/b/c.txt` | `file.jpg` |
| `dir/**` | Any file under dir | `dir/file.txt`, `dir/sub/file.jpg` | `root/file.txt` |
| `**/dir` | Any dir named "dir" | `dir`, `a/b/dir` | `dir/file`, `dirname` |
| `root/**test` (same as `root/**/test`) | Files named "test" in any subdir of root | `root/test`, `root/a/b/test` | `root/testfile`, `root/file` |


## TOML Rule Structure

### Simple rules:

```toml
[[rules]]
"a/**" = "task"
"b/**" = "task"
```

### Nested rules:

```toml
[[rules."a"]]
"1/**" = "task"
"2/**" = "task"

# Equivalent to:
[[rules]]
"a/1/**" = "task"
"a/2/**" = "task"
```

Nested rules may use wildcards:

```toml
[[rules."a/**/"]]
"1/**" = "task"
"2/**" = "task"

# Equivalent to:
[[rules]]
"a/**/1/**" = "task"
"a/**/2/**" = "task"
```


# Tools

## Bash
Executes bash scripts. The following environment variables are available:

- `PICK_FILE`: Absolute path to the current file
- `PICK_RELATIVE`: Relative path (from the source directory)