# dosh - The Simplest Build Tool on Earth

dosh is a minimal task runner pattern for shell scripts. Each dosh script is a standalone bash file where functions become tasks you can run from the command line.

Based on [8gears/do](https://github.com/8gears/do).

## How It Works

A dosh script defines functions, then uses `"$@"` to execute whatever function name is passed as an argument:

```bash
#!/usr/bin/env bash

build() {
    echo "Building..."
}

test() {
    echo "Testing..."
}

"$@"
```

Run it with:
```bash
./dosh build    # runs build()
./dosh test     # runs test()
```

## Sample Script

A complete sample dosh script is available: [dosh.sh](dosh.sh)

## Convention: Private Functions

Functions starting with `_` are considered private/helper functions and won't appear in usage output or tab completion:

```bash
_helper() {
    echo "I'm a helper"
}

build() {
    _helper
    echo "Building..."
}
```

## Usage Output

Add this at the end of your dosh script to show available tasks when run without arguments:

```bash
"$@"
[ "$#" -gt 0 ] || printf "Usage:\n\t./${SCRIPTNAME} %s\n" "($(compgen -A function | grep '^[^_]' | paste -sd '|' -))"
```

## Tab Completion

### Bash

Add the `--completions` handler to your dosh script, just before the `"$@"` line:

```bash
if [[ "$1" == "--completions" ]]; then
    compgen -A function | grep '^[^_]'
    exit 0
fi

"$@"
```

Then add this to your `~/.bashrc`:

```bash
_dosh_complete() {
    local cur="${COMP_WORDS[COMP_CWORD]}"
    local script="${COMP_WORDS[0]}"
    COMPREPLY=($(compgen -W "$($script --completions 2>/dev/null)" -- "$cur"))
}
complete -F _dosh_complete dosh
complete -F _dosh_complete ./dosh
```

After reloading your shell (`source ~/.bashrc`), tab completion will work:
```bash
./dosh bu<TAB>  # completes to ./dosh build
```

### Zsh

The same `--completions` handler in your dosh script works for zsh. Add this to your `~/.zshrc`:

```zsh
_dosh_complete() {
    local completions
    completions=(${(f)"$($words[1] --completions 2>/dev/null)"})
    _describe 'tasks' completions
}
compdef _dosh_complete dosh
compdef _dosh_complete ./dosh
```

## direnv Integration

A common pattern is to put dosh in `bin/dosh` and add `bin` to your PATH using direnv. This lets you run `dosh build` instead of `./bin/dosh build` from anywhere in the project.

Example `.envrc`:
```bash
PATH_add bin
```

See [envrc](https://code.librehq.com/james/envrc) for a more complete direnv setup.

With this pattern, add a completion registration for `dosh` (without the `./`):

```bash
complete -F _dosh_complete dosh      # bash
compdef _dosh_complete dosh          # zsh
```

## Tips

- **Root access**: Functions needing root should check for it and fail early
- **Working directory**: Use `BASEDIR` to ensure consistent paths regardless of where the script is invoked from
- **Dependencies**: Consider a `deps` or `setup-dev` task to install required tools