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