| 1 |
# Shell prompt integration |
| 2 |
|
| 3 |
`oxy prompt` prints one line about the current repository in a few |
| 4 |
milliseconds and records nothing. Outside an Oxygen repository it prints |
| 5 |
nothing and exits 1, so it is safe to call from any prompt. |
| 6 |
|
| 7 |
``` |
| 8 |
$ oxy prompt |
| 9 |
main 658990aa*+2 |
| 10 |
``` |
| 11 |
|
| 12 |
That is bookmark, working-copy change id, `*` when the working copy has |
| 13 |
uncommitted changes, `!` when the state has conflicts, and `+n`/`-n` for |
| 14 |
changes ahead of and behind `origin`. The default format is `%b %c%d%x%A%D`; |
| 15 |
`--format` takes any string with these placeholders: |
| 16 |
|
| 17 |
|
| 18 |
|
| 19 |
| `%b` | bookmark | |
| 20 |
| `%c` | working-copy ChangeId prefix | |
| 21 |
| `%h` | number of heads | |
| 22 |
| `%d` | `*` when dirty | |
| 23 |
| `%x` | `!` when the base state has conflicts | |
| 24 |
| `%A` / `%D` | `+n` ahead / `-n` behind origin, empty when zero or unknown | |
| 25 |
| `%a` / `%B` | raw ahead / behind counts | |
| 26 |
| `%s` | state glyph: `✔` clean, `✎` dirty, `‼` conflicted | |
| 27 |
| `%U` / `%O` | `↑n` ahead / `↓n` behind origin, empty when zero or unknown | |
| 28 |
| `%i` | the repository icon `⚛` | |
| 29 |
| `%%` | a percent sign | |
| 30 |
|
| 31 |
`--glyphs` selects the format `%i %b %c %s%U%O` (`⚛ main 658990aa ✎↑2`), and |
| 32 |
`--color raw|bash|zsh` wraps the line in the state's colour (cyan clean, |
| 33 |
yellow dirty, red conflicted), guarded so bash and zsh measure the prompt |
| 34 |
correctly: |
| 35 |
|
| 36 |
```bash |
| 37 |
PS1='\u@\h \w $(oxy prompt --glyphs --color bash 2>/dev/null)\$ ' |
| 38 |
``` |
| 39 |
|
| 40 |
Dirtiness is decided from a manifest written at every snapshot and checkout: |
| 41 |
files are compared by size and modification time first and by content hash |
| 42 |
only when those differ, so the cost is one directory walk. |
| 43 |
|
| 44 |
## oh-my-bash powerline themes |
| 45 |
|
| 46 |
For the `powerline`, `powerline-icon`, `powerline-multiline`, and |
| 47 |
`powerline-plain` themes, copy [contrib/oh-my-bash/oxy.sh](../contrib/oh-my-bash/oxy.sh) |
| 48 |
to `~/.oh-my-bash/custom/oxy.sh` and open a new shell. It adds an `oxy` |
| 49 |
segment beside the Git one, coloured by state, showing icon, bookmark, |
| 50 |
change id, state glyph, and ahead/behind arrows. The file's variables |
| 51 |
(`POWERLINE_OXY_CHAR`, `OXY_THEME_PROMPT_*_COLOR`, `OXY_THEME_PROMPT_*_GLYPH`) |
| 52 |
can be overridden in `~/.bashrc` before oh-my-bash loads, and |
| 53 |
`POWERLINE_PROMPT` arranges the segments. |
| 54 |
|
| 55 |
## bash and oh-my-bash (other themes) |
| 56 |
|
| 57 |
Add to `~/.bashrc` (or to a custom oh-my-bash theme in |
| 58 |
`~/.oh-my-bash/custom/themes/<name>/<name>.theme.sh`): |
| 59 |
|
| 60 |
```bash |
| 61 |
# Oxygen repository info for the prompt; silent outside a repository. |
| 62 |
oxy_prompt_info() { |
| 63 |
local info |
| 64 |
info=$(oxy prompt --format '%b %c%d%x%A%D' 2>/dev/null) || return |
| 65 |
local color='\[\e[36m\]' reset='\[\e[0m\]' warn='\[\e[33m\]' |
| 66 |
case "$info" in |
| 67 |
*'*'*|*'!'*) printf ' %b(%s)%b' "$warn" "$info" "$reset" ;; |
| 68 |
*) printf ' %b(%s)%b' "$color" "$info" "$reset" ;; |
| 69 |
esac |
| 70 |
} |
| 71 |
``` |
| 72 |
|
| 73 |
Then reference it from `PS1`, next to your Git info: |
| 74 |
|
| 75 |
```bash |
| 76 |
PS1='\u@\h \w$(git_prompt_info 2>/dev/null)$(oxy_prompt_info)\$ ' |
| 77 |
``` |
| 78 |
|
| 79 |
With oh-my-bash, most themes build the prompt in a function such as |
| 80 |
`_omb_theme_PROMPT_COMMAND`; append `$(oxy_prompt_info)` to the `PS1` |
| 81 |
assignment there, or copy the theme into `custom/themes` and edit that copy |
| 82 |
so updates do not overwrite it. |
| 83 |
|
| 84 |
## zsh |
| 85 |
|
| 86 |
```zsh |
| 87 |
oxy_prompt_info() { |
| 88 |
local info |
| 89 |
info=$(oxy prompt 2>/dev/null) || return |
| 90 |
print -n " %F{cyan}($info)%f" |
| 91 |
} |
| 92 |
setopt PROMPT_SUBST |
| 93 |
PROMPT='%n@%m %~$(oxy_prompt_info) %# ' |
| 94 |
``` |
| 95 |
|
| 96 |
## Notes |
| 97 |
|
| 98 |
- The dirty and conflict markers come from the manifest written by the last |
| 99 |
`oxy status`, commit, or checkout; in a repository that has never been |
| 100 |
snapshotted they are blank until the first `oxy status`. |
| 101 |
|
| 102 |
- The counts against `origin` use the tracking state from the last |
| 103 |
`oxy fetch`, `pull`, or `push`; the prompt never contacts the network. |
| 104 |
- `oxy prompt` uses plain text by default so shells can colour it; colour is |
| 105 |
added in the shell function, not by oxy. |