| 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 |
| `%%` | a percent sign | |
| 27 |
|
| 28 |
Dirtiness is decided from a manifest written at every snapshot and checkout: |
| 29 |
files are compared by size and modification time first and by content hash |
| 30 |
only when those differ, so the cost is one directory walk. |
| 31 |
|
| 32 |
## bash and oh-my-bash |
| 33 |
|
| 34 |
Add to `~/.bashrc` (or to a custom oh-my-bash theme in |
| 35 |
`~/.oh-my-bash/custom/themes/<name>/<name>.theme.sh`): |
| 36 |
|
| 37 |
```bash |
| 38 |
# Oxygen repository info for the prompt; silent outside a repository. |
| 39 |
oxy_prompt_info() { |
| 40 |
local info |
| 41 |
info=$(oxy prompt --format '%b %c%d%x%A%D' 2>/dev/null) || return |
| 42 |
local color='\[\e[36m\]' reset='\[\e[0m\]' warn='\[\e[33m\]' |
| 43 |
case "$info" in |
| 44 |
*'*'*|*'!'*) printf ' %b(%s)%b' "$warn" "$info" "$reset" ;; |
| 45 |
*) printf ' %b(%s)%b' "$color" "$info" "$reset" ;; |
| 46 |
esac |
| 47 |
} |
| 48 |
``` |
| 49 |
|
| 50 |
Then reference it from `PS1`, next to your Git info: |
| 51 |
|
| 52 |
```bash |
| 53 |
PS1='\u@\h \w$(git_prompt_info 2>/dev/null)$(oxy_prompt_info)\$ ' |
| 54 |
``` |
| 55 |
|
| 56 |
With oh-my-bash, most themes build the prompt in a function such as |
| 57 |
`_omb_theme_PROMPT_COMMAND`; append `$(oxy_prompt_info)` to the `PS1` |
| 58 |
assignment there, or copy the theme into `custom/themes` and edit that copy |
| 59 |
so updates do not overwrite it. |
| 60 |
|
| 61 |
## zsh |
| 62 |
|
| 63 |
```zsh |
| 64 |
oxy_prompt_info() { |
| 65 |
local info |
| 66 |
info=$(oxy prompt 2>/dev/null) || return |
| 67 |
print -n " %F{cyan}($info)%f" |
| 68 |
} |
| 69 |
setopt PROMPT_SUBST |
| 70 |
PROMPT='%n@%m %~$(oxy_prompt_info) %# ' |
| 71 |
``` |
| 72 |
|
| 73 |
## Notes |
| 74 |
|
| 75 |
- The dirty and conflict markers come from the manifest written by the last |
| 76 |
`oxy status`, commit, or checkout; in a repository that has never been |
| 77 |
snapshotted they are blank until the first `oxy status`. |
| 78 |
|
| 79 |
- The counts against `origin` use the tracking state from the last |
| 80 |
`oxy fetch`, `pull`, or `push`; the prompt never contacts the network. |
| 81 |
- `oxy prompt` uses plain text by default so shells can colour it; colour is |
| 82 |
added in the shell function, not by oxy. |