statusline 0.23.0

Simple and fast bash PS1 line with useful features
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

# statusline

A blazingly-fast[^fast] successor to purplesyringa's [shell](https://github.com/purplesyringa/shell.git),
rewritten in Rust.

[^fast]: compared to `shell`, but this claim was made off general vibes and might have been wrong.
It is probably faster, though not by that much.

TODO: maybe some screenshots to show what it's like?

## Requirements

* a decently modern linux kernel
* bash, obviously
* git binary (optional, recommended)
* cargo or nix
* a little bit of time and patience

## Installation

0. Install rustup and stable rust.
   ```bash
   pacman -S rustup
   rustup toolchain add stable
   ```
   Visit [rustup.rs](https://rustup.rs/) if not on Arch-based distro to see how to install on other distros.
   You may need to run rustup installation with superuser rights

1. Install statusline from cargo
   ```bash
   cargo install statusline
   ```

2. Check if statusline is in path.
   ```bash
   statusline
   ```
   If "bash: statusline: command not found" is shown,
   check your `$PATH` and `~/.bashrc`,
   a folder where cargo install placed statusline binary should be there.

   If you wish to not add the directory to `$PATH`,
   you can just use full path instead of short one in `statusline env` below

3. Install the statusline to shell
   ```bash
   echo 'source <(statusline env)' >> ~/.bashrc
   ```

4. Apply changes immediately
   ```bash
   PS1_MODE=minimal source <(statusline env)
   ```

Don't forget to check `$PATH` and update from time to time.

## Nix way

Build and apply immediately:
```bash
nix-build --log-format multiline-with-logs && source <(result/bin/statusline env)
```

NixOS usage example can be found in [my configuration](https://codeberg.org/sylfn/dotfiles/src/commit/06d2b6a512959675479a86811ea28db2c628fc22/modules/statusline.nix).

## Features

Like any fancy PS1, this one supports color.
It detects tmux and tty and resets itself to text-friendly mode,
and also detects terminals that call themselves dumb and doesn't modify PS1 in that case at all.

statusline simplifies displayed paths.
`/home/<yourusername>` becomes `~`,
and `/home/<another>` becomes `~another`, like bash tilde expansion, but in reverse.

statusline integrates with Git
and is able to show basic information about repositories it encounters
even without git binary present.

One notable feature, though, is colorized hostnames, usernames and git branches.
They get assigned a random color and it helps differentiate between hosts, users and branches.
The color red is reserved for `root`.
The colors displayed are "true" (24-bit),
meaning that tty or other lesser-color terminals may collide some colors and revert the disambiguation.

## Customization

statusline has limited customization options.
All customization options are set with `PS1_...` environment variables.

### `PS1_MODE`: Icon set

- unset: use default nerd font icon set
- `minimal`: use alternative nerd font icon set which is somewhat simpler but may be perplexing
- `text`: always use ASCII text

statusline automatically detects dumb terminals and does nothing,
and it also detects tty/tmux/screen and falls back to text mode on these
as these might not support nerd fonts.

### Block order

statusline has four groups of blocks: left, middle, right, and bottom,
which are arranged in two or three lines depending on the width:

- two-line: left middle _ right / bottom
- three-line: left _ right / middle / bottom

Only left blocks support dynamic updates.

Supported blocks and their default placement are listed below.

- L`host_user`: hostname, username, chassis
- L`ssh`: ssh sesion, workgroup ssh chain
- L`git_repo`: git branch, git state, stash count; *dynamic*: ahead-behind
- L`git_tree`: *dynamic*: number of staged, modified, untracked, or unmerged files
- L`build_info`: detected magic files such as `Cargo.toml` or `default.nix`
- L`nix_shell`: nix-shell, nix3 shells, direnv environments
- L`venv`: python venv
- M`workdir`: working directory with homes folded and most nested git repo highlighted
- R`elapsed`: previous command elapsed time
- R`return_code`: previous command return code, `$?`
- R`unseen_mail`: like `$MAILCHECK` in bash
- R`jobs`: background jobs count
- R`time`: current date and time
- B`root_shell`: is current user root, `$SHLVL`

`PS1_LEFT`, `PS1_MIDDLE`, `PS1_RIGHT`, `PS1_BOTTOM` variables accept comma-separated list of block names.

## How is this different from purplesyringa's shell?

There once was a bashful list of why one should use this version over the bash one,
but the gist of it is that the bash version was slow, unmaintained, buggy, and a maintenance burden.

## Command line options

### `statusline` (without args)

Shows the version, link to the repo, and a simple how-to-use message.

### `statusline [command] --help` or `statusline help [command]`

Shows help messages.

### `statusline env`

Prints contents of [what's executed by recommended bashrc snippet](./src/shell.sh).
Do not source the snippet directly, as its contents will change without notice.

### `statusline run [...options]`

This command is run by bash at every PS1 instantiation.
One can run it without bash to profile the prompt,
or to see how the PS1 would look without installing PS1 into the shell.
Some arguments have defaults that are only set from within "env" script.

### `statusline create`, `statusline chain` and `ssh` alias

Undocumented ssh workgroup feature.
Never got to documenting it, basically.