2019-09-17 02:54:39 +00:00
# bottom
2019-09-04 03:27:25 +00:00
2019-09-18 18:52:18 +00:00
[](https://travis-ci.com/ClementTsang/bottom) [](https://crates.io/crates/bottom)
2019-09-15 02:29:40 +00:00
2020-01-25 21:44:16 +00:00
A graphical top clone, written in Rust. Inspired by both [gtop ](https://github.com/aksakalli/gtop ) and [gotop ](https://github.com/cjbassi/gotop ).
2019-09-04 03:27:25 +00:00
2020-02-03 00:08:21 +00:00
 _Terminal: Kitty Terminal, Font: IBM Plex Mono, OS: Arch Linux_
2019-09-17 01:45:48 +00:00
2020-01-12 23:45:11 +00:00
## Features
Features of bottom include:
- CPU widget to show a visual representation of per-core usage. Average CPU display also exists.
- Memory widget to show a visual representation of both RAM and SWAP usage.
- Networks widget to show a log-based visual representation of network usage.
- Sortable and searchable process widget. Searching supports regex, and you can search by PID and process name.
- Disks widget to display usage and I/O per second.
- Temperature widget to monitor detected sensors in your system.
The compatibility of each widget and operating systems are, as of version 0.1.0, as follows:
2020-02-03 04:35:50 +00:00
| OS | CPU | Memory | Disks | Temperature | Processes | Networks |
2020-01-31 04:33:33 +00:00
| -------------------------------- | --- | ------ | ----- | ----------- | --------- | --------------------- |
| Linux (tested on Arch Linux) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Windows (tested on Windows 10) | ✓ | ✓ | ✓ | ✗ | ✓ | Total RX/TX not shown |
| macOS (tested on macOS Catalina) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
2020-01-12 23:45:11 +00:00
2019-09-09 04:09:58 +00:00
## Installation
2019-09-05 22:28:54 +00:00
2020-02-04 04:27:44 +00:00
In all cases you can install the in-development version by cloning and using `cargo build --release` . Note this is built and tested with Rust Stable (1.41.0 as of writing). You can also get release versions using `cargo install bottom` , or manually building from the [Releases ](https://github.com/ClementTsang/bottom/releases ) page by downloading and building.
2020-01-19 07:02:44 +00:00
2019-09-09 04:09:58 +00:00
### Linux
2020-01-19 07:02:44 +00:00
Other installation methods based on distros are as follows:
2020-01-10 03:31:49 +00:00
#### Arch Linux
2020-01-12 19:25:47 +00:00
You can get the release versions from the AUR by installing `bottom` .
2020-01-05 00:20:54 +00:00
2020-02-03 04:35:50 +00:00
#### Ubuntu
TBD
2019-09-09 04:09:58 +00:00
### Windows
2020-02-03 04:35:50 +00:00
You may need to install a font like [FreeMono ](https://fonts2u.com/free-monospaced.font ) and use a terminal like cmder for font support to work properly, unfortunately. I plan to add a Chocolatey install option in the future.
2019-09-09 04:09:58 +00:00
2019-12-17 07:11:16 +00:00
### macOS
2019-09-09 04:09:58 +00:00
2020-02-03 04:35:50 +00:00
macOS seems to work fine for the most part, barring minor issues with the `Ctrl` -arrow key bindings (use `Shift` instead). I plan to add a Homebrew install option in the future.
2019-09-08 05:28:03 +00:00
2020-01-03 01:31:58 +00:00
## Usage
2019-10-10 22:05:26 +00:00
2020-01-10 04:36:24 +00:00
Run using `btm` .
2019-09-17 02:39:57 +00:00
### Command line options
2019-12-16 07:40:35 +00:00
- `-h` , `--help` shows the help screen and exits.
2019-09-17 02:39:57 +00:00
2020-02-05 01:05:07 +00:00
- `-a` , `--avg_cpu` enables also showing the average CPU usage in addition to per-core CPU usage.
2019-09-25 05:54:38 +00:00
2019-12-16 07:40:35 +00:00
- `-m` , `--dot-marker` uses a dot marker instead of the default braille marker.
2019-09-17 02:39:57 +00:00
2020-02-05 01:05:07 +00:00
- Temperature units (you can only use one at a time):
2019-09-17 02:39:57 +00:00
2020-02-05 01:05:07 +00:00
- `-c` , `--celsius` displays the temperature type in Celsius. This is the default.
2019-09-17 02:39:57 +00:00
2020-02-05 01:05:07 +00:00
- `-f` , `--fahrenheit` displays the temperature type in Fahrenheit.
- `-k` , `--kelvin` displays the temperature type in Kelvin.
2019-09-17 02:39:57 +00:00
2019-09-25 05:34:33 +00:00
- `-v` , `--version` displays the version number and exits.
2019-09-17 02:39:57 +00:00
2019-12-13 04:03:34 +00:00
- `-d` , `--debug` enables debug logging.
2019-12-26 00:00:24 +00:00
- `-r <RATE>` , `--rate <RATE>` will set the refresh rate in _milliseconds_ . Lowest it can go is 250ms, the highest it can go is 2< sup > 128</ sup > - 1. Defaults to 1000ms, and lower values may take more resources due to more frequent polling of data, and may be less accurate in some circumstances.
2019-09-17 02:39:57 +00:00
2019-12-28 06:21:49 +00:00
- `-l` , `--left_legend` will move external table legends to the left side rather than the right side. Right side is default.
2020-01-03 04:42:44 +00:00
- `-u` , `--current_usage` will make a process' CPU usage be based on the current total CPU usage, rather than assuming 100% CPU usage. Only affects Linux for now.
2020-01-01 03:24:54 +00:00
2020-01-18 00:59:01 +00:00
- `-g` , `--group` will group together processes with the same name by default (equivalent to pressing `Tab` ).
2020-02-05 01:05:07 +00:00
- `-S` , `--case_sensitive` will default to matching case.
2020-02-03 04:20:53 +00:00
2020-02-05 01:05:07 +00:00
- `-W` , `--whole` will default to searching for the world word.
2020-02-03 04:20:53 +00:00
2020-02-05 01:05:07 +00:00
- `-R` , `--regex` will default to using regex.
2020-02-02 04:49:44 +00:00
2020-02-08 19:28:19 +00:00
- `-C` , `--config` takes in a file path leading to a TOML file.
2020-02-07 05:28:26 +00:00
2020-02-08 19:28:19 +00:00
One use of a config file is to set flags to execute by default.
2020-02-08 19:38:16 +00:00
- This is set under the `[flags]` section.
- These options are generally the same as the long names as other flags (ex: `case_sensitive = true` ).
2020-02-08 19:28:19 +00:00
- For temperature type, use `temperature_type = "<kelvin|k|celsius|c|fahrenheit|f>"` .
2020-02-08 19:38:16 +00:00
Another use is to set colours, under the `[colors]` . The following labels are customizable with hex colour code strings:
2020-02-08 19:28:19 +00:00
- Table header colours (`table_header_color="#ffffff"`).
2020-02-08 19:38:16 +00:00
- Every CPU core colour as an array (`cpu_core_colors=["#ffffff", "#000000", "#111111"]`).
- bottom will look at 216 (let's be realistic here) colours at most, and in order.
- If not enough colours are provided for the number of threads on the CPU, then the rest will be automatically generated.
2020-02-08 19:28:19 +00:00
- RAM and SWAP colours (`ram_color="#ffffff"`, `swap_color="#111111"` ).
- RX and TX colours (`rx_color="#ffffff"`, `tx_color="#111111"` ).
2020-02-08 19:38:16 +00:00
- Widget title colour (`widget_title_color="#ffffff"`).
2020-02-08 19:28:19 +00:00
- General widget border colour (`border_color="#ffffff"`).
- Current widget border colour (`highlighted_border_color="#ffffff"`).
- Text colour (`text_color="#ffffff"`).
2020-02-08 19:38:16 +00:00
- Label and graph colour (`graph_color="#ffffff"`).
2020-02-08 19:28:19 +00:00
- Cursor colour (`cursor_color="#ffffff"`).
- Current selected scroll entry colour (`scroll_entry_text_color="#282828"`, `scroll_entry_bg_color="#458588"` ).
2020-02-07 05:28:26 +00:00
bottom will check specific locations by default for a config file.
- For Unix-based systems: `~/.config/btm/btm.toml` .
- For Windows: TBD.
2020-01-09 03:54:14 +00:00
2020-02-08 19:38:16 +00:00
See this [config ](./sample_config.toml ) for an example.
2020-02-08 19:28:19 +00:00
2019-12-22 22:37:07 +00:00
### Keybindings
2019-09-17 01:45:48 +00:00
#### General
2020-01-12 20:41:27 +00:00
- `q` , `Ctrl-c` to quit. Note if you are currently in the search widget, `q` will not work so you can still type.
2019-10-10 22:01:23 +00:00
- `Ctrl-r` to reset the screen and reset all collected data.
2019-09-17 01:45:48 +00:00
2019-10-10 02:50:36 +00:00
- `f` to freeze the screen from updating with new data. Press `f` again to unfreeze. Note that monitoring will still continue in the background.
2019-10-10 02:34:09 +00:00
2020-02-02 22:48:46 +00:00
- `Ctrl/Shift-Up` , `Ctrl/Shift-Down` , `Ctrl/Shift-Left` , and `Ctrl/Shift-Right` to navigate between widgets. **Note that on macOS, `Ctrl`-arrow keys conflicts with an existing macOS binding, use `Shift`-arrow key instead.**
2019-09-25 20:43:13 +00:00
2019-10-10 02:42:50 +00:00
- `Esc` to close a dialog window.
2019-10-10 02:00:10 +00:00
2019-10-10 02:50:36 +00:00
- `?` to get a help screen explaining the controls. Note all controls except `Esc` to close the dialog will be disabled while this is open.
2019-09-17 01:45:48 +00:00
2020-01-03 05:00:05 +00:00
#### Scrollable Tables
2020-01-12 19:25:47 +00:00
- `Up` or `k` and `Down` or `j` scrolls through the list if the widget is a table (Temperature, Disks, Processes).
2020-01-03 05:00:05 +00:00
2020-01-05 00:41:32 +00:00
- `gg` or `Home` to jump to the first entry of the current table.
2020-01-03 05:00:05 +00:00
2020-01-12 18:15:35 +00:00
- `G` (`Shift-g`) or `End` to jump to the last entry of the current table.
2020-01-03 05:00:05 +00:00
#### Processes
2019-09-17 01:45:48 +00:00
2019-12-31 02:05:39 +00:00
- `dd` to kill the selected process
2019-09-17 01:45:48 +00:00
2019-09-25 05:34:33 +00:00
- `c` to sort by CPU usage. Sorts in descending order by default. Press again to reverse sorting order.
2019-09-17 01:45:48 +00:00
2019-09-25 05:34:33 +00:00
- `m` to sort by memory usage. Sorts in descending order by default. Press again to reverse sorting order.
2019-09-17 01:45:48 +00:00
2019-09-25 05:34:33 +00:00
- `p` to sort by PID. Sorts in ascending order by default. Press again to reverse sorting order.
2019-09-17 01:45:48 +00:00
2019-09-25 05:34:33 +00:00
- `n` to sort by process name. Sorts in ascending order by default. Press again to reverse sorting order.
2019-09-17 01:45:48 +00:00
2020-01-09 03:54:14 +00:00
- `Tab` to group together processes with the same name. Disables PID sorting. `dd` will now kill all processes covered by that name.
2020-01-12 23:45:11 +00:00
- `Ctrl-f` or `/` to open the search widget.
#### Search Widget
2020-02-03 04:20:53 +00:00
- `Tab` to switch between searching for PID and name respectively.
- `Alt-c` to toggle ignoring case.
- `Alt-m` to toggle matching the entire word.
2020-01-12 23:45:11 +00:00
2020-02-03 04:20:53 +00:00
- `Alt-r` to toggle using regex.
2020-01-18 00:59:01 +00:00
- `Ctrl-a` and `Ctrl-e` to jump to the start and end of the search bar respectively.
2020-01-25 01:00:37 +00:00
- `Esc` to close.
2020-01-12 23:45:11 +00:00
2020-01-22 00:28:39 +00:00
- `Left` and `Right` arrow keys to move the cursor within the search bar.
2020-01-12 23:45:11 +00:00
Note that `q` is disabled while in the search widget.
2020-01-12 19:25:47 +00:00
2019-12-17 07:11:16 +00:00
### Mouse actions
2019-09-17 01:45:48 +00:00
2020-01-22 00:28:39 +00:00
- Scrolling with the mouse will scroll through the currently selected list if the widget is a scrollable table.
2019-12-31 02:05:39 +00:00
2019-12-17 07:11:16 +00:00
## Thanks, kudos, and all the like
2019-09-04 03:27:25 +00:00
2020-01-22 00:28:39 +00:00
- This project is very much inspired by both [gotop ](https://github.com/cjbassi/gotop ) and [gtop ](https://github.com/aksakalli/gtop ).
2019-09-25 05:34:33 +00:00
- This application was written with the following libraries:
2020-02-02 23:06:19 +00:00
- [backtrace ](https://github.com/rust-lang/backtrace-rs )
2019-09-25 05:34:33 +00:00
- [chrono ](https://github.com/chronotope/chrono )
- [clap ](https://github.com/clap-rs/clap )
- [crossterm ](https://github.com/TimonPost/crossterm )
- [failure ](https://github.com/rust-lang-nursery/failure )
- [fern ](https://github.com/daboross/fern )
- [futures-rs ](https://github.com/rust-lang-nursery/futures-rs )
- [futures-timer ](https://github.com/rustasync/futures-timer )
- [heim ](https://github.com/heim-rs/heim )
2020-02-02 23:06:19 +00:00
- [lazy_static ](https://github.com/rust-lang-nursery/lazy-static.rs )
2019-09-25 05:34:33 +00:00
- [log ](https://github.com/rust-lang-nursery/log )
- [sysinfo ](https://github.com/GuillaumeGomez/sysinfo )
- [tokio ](https://github.com/tokio-rs/tokio )
2019-12-13 04:03:34 +00:00
- [tui-rs ](https://github.com/fdehau/tui-rs )
2019-09-25 05:34:33 +00:00
- [winapi ](https://github.com/retep998/winapi-rs )
2020-02-02 23:06:19 +00:00
- [yaml-rust ](https://github.com/chyh1990/yaml-rust )
