# Shell prompt integration

`oxy prompt` prints one line about the current repository in a few
milliseconds and records nothing. Outside an Oxygen repository it prints
nothing and exits 1, so it is safe to call from any prompt.

```
$ oxy prompt
main 658990aa*+2
```

That is bookmark, working-copy change id, `*` when the working copy has
uncommitted changes, `!` when the state has conflicts, and `+n`/`-n` for
changes ahead of and behind `origin`. The default format is `%b %c%d%x%A%D`;
`--format` takes any string with these placeholders:

| Placeholder | Meaning |
|---|---|
| `%b` | bookmark |
| `%c` | working-copy ChangeId prefix |
| `%h` | number of heads |
| `%d` | `*` when dirty |
| `%x` | `!` when the base state has conflicts |
| `%A` / `%D` | `+n` ahead / `-n` behind origin, empty when zero or unknown |
| `%a` / `%B` | raw ahead / behind counts |
| `%%` | a percent sign |

Dirtiness is decided from a manifest written at every snapshot and checkout:
files are compared by size and modification time first and by content hash
only when those differ, so the cost is one directory walk.

## bash and oh-my-bash

Add to `~/.bashrc` (or to a custom oh-my-bash theme in
`~/.oh-my-bash/custom/themes/<name>/<name>.theme.sh`):

```bash
# Oxygen repository info for the prompt; silent outside a repository.
oxy_prompt_info() {
  local info
  info=$(oxy prompt --format '%b %c%d%x%A%D' 2>/dev/null) || return
  local color='\[\e[36m\]' reset='\[\e[0m\]' warn='\[\e[33m\]'
  case "$info" in
    *'*'*|*'!'*) printf ' %b(%s)%b' "$warn" "$info" "$reset" ;;
    *)           printf ' %b(%s)%b' "$color" "$info" "$reset" ;;
  esac
}
```

Then reference it from `PS1`, next to your Git info:

```bash
PS1='\u@\h \w$(git_prompt_info 2>/dev/null)$(oxy_prompt_info)\$ '
```

With oh-my-bash, most themes build the prompt in a function such as
`_omb_theme_PROMPT_COMMAND`; append `$(oxy_prompt_info)` to the `PS1`
assignment there, or copy the theme into `custom/themes` and edit that copy
so updates do not overwrite it.

## zsh

```zsh
oxy_prompt_info() {
  local info
  info=$(oxy prompt 2>/dev/null) || return
  print -n " %F{cyan}($info)%f"
}
setopt PROMPT_SUBST
PROMPT='%n@%m %~$(oxy_prompt_info) %# '
```

## Notes

- The dirty and conflict markers come from the manifest written by the last
  `oxy status`, commit, or checkout; in a repository that has never been
  snapshotted they are blank until the first `oxy status`.

- The counts against `origin` use the tracking state from the last
  `oxy fetch`, `pull`, or `push`; the prompt never contacts the network.
- `oxy prompt` uses plain text by default so shells can colour it; colour is
  added in the shell function, not by oxy.