# 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 |
| `%s` | state glyph: `✔` clean, `✎` dirty, `‼` conflicted |
| `%U` / `%O` | `↑n` ahead / `↓n` behind origin, empty when zero or unknown |
| `%i` | the repository icon `⚛` |
| `%%` | a percent sign |

`--glyphs` selects the format `%i %b %c %s%U%O` (`⚛ main 658990aa ✎↑2`), and
`--color raw|bash|zsh` wraps the line in the state's colour (cyan clean,
yellow dirty, red conflicted), guarded so bash and zsh measure the prompt
correctly:

```bash
PS1='\u@\h \w $(oxy prompt --glyphs --color bash 2>/dev/null)\$ '
```

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.

## oh-my-bash powerline themes

For the `powerline`, `powerline-icon`, `powerline-multiline`, and
`powerline-plain` themes, copy [contrib/oh-my-bash/oxy.sh](../contrib/oh-my-bash/oxy.sh)
to `~/.oh-my-bash/custom/oxy.sh` and open a new shell. It adds an `oxy`
segment beside the Git one, coloured by state, showing icon, bookmark,
change id, state glyph, and ahead/behind arrows. The file's variables
(`POWERLINE_OXY_CHAR`, `OXY_THEME_PROMPT_*_COLOR`, `OXY_THEME_PROMPT_*_GLYPH`)
can be overridden in `~/.bashrc` before oh-my-bash loads, and
`POWERLINE_PROMPT` arranges the segments.

## bash and oh-my-bash (other themes)

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.