statusline 0.22.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

# 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. Set preferred statusline icons' mode.
4. Do not add this line for defaults!
   Available modes are:
   - `PS1_MODE=text`: use ASCII text instead of icons
   - `PS1_MODE=minimal`: use alternative icon set which is somewhat simpler but may be perplexing
   - otherwise: use default nerdfont icons
   ```bash
   echo 'export PS1_MODE=minimal' >> ~/.bashrc
   ```

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

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

None of the colors and format strings are customizable,
but the order of them is (or will be soon).

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

- `statusline run [--return-code <c>] --jobs-count <j> [--elapsed-time <t>] [--control-fd <f>] [--mode <m>]`

  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.

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

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