Mirrors/bottom
2
0
Fork 0
mirror of https://github.com/ClementTsang/bottom synced 2024-12-14 06:32:32 +00:00
Code Issues Projects Releases Packages Wiki Activity
bottom/docs/content/usage/widgets/process.md

228 lines
12 KiB
Markdown
Raw Normal View History

docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
# Process Widget
The process widget displays a table containing information regarding a running process, along with sorting,
searching, and process control features.
<figure>
docs: Switch to webp, fix some sections (#514) Switches to webp and fixes some typos/poor wording.
2021-06-22 02:53:25 +00:00
<img src="../../../assets/screenshots/process/process_default.webp" alt="A picture of an expanded process widget by default."/>
docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
</figure>
## Features
The process widget has three main components:
- The main process table
- The search sub-widget (opened with ++ctrl+f++ or ++slash++)
- The sort menu sub-widget (opened with ++s++ or ++f6++)
By default, the main process table displays the following information for each process:
- PID
- Name of the process
- CPU use percentage (note this is averaged out per available thread)
- Memory use percentage
- Reads per second
- Writes per second
- Total amount read
- Total amount written
- User
- State
### Sorting
The table can be sorted by clicking on the table headers, which will either sort the table by that column, or if already
sorting by that column, reverse the sorting order.
Alternatively, one can sort using the sort menu sub-widget, which is brought up using ++s++ or ++f6++, and can be controlled by arrow keys or the mouse.
<figure>
docs: Switch to webp, fix some sections (#514) Switches to webp and fixes some typos/poor wording.
2021-06-22 02:53:25 +00:00
<img src="../../../assets/screenshots/process/process_sort_menu.webp" alt="A picture of an expanded process widget with the sort menu open."/>
docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
</figure>
### Grouping
Pressing ++tab++ in the table will group entries with the same name together. The PID column will be replaced with the number of entries in each group, and usage
is added together when displayed.
<figure>
docs: Switch to webp, fix some sections (#514) Switches to webp and fixes some typos/poor wording.
2021-06-22 02:53:25 +00:00
<img src="../../../assets/screenshots/process/process_grouped.webp" alt="A picture of grouped mode in a process widget."/>
docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
</figure>
Note that the process state and user columns are disabled in this mode.
### Tree mode
Pressing ++t++ or ++f5++ in the table toggles tree mode in the process widget, displaying processes in regards to their parent-child process relationships.
<figure>
docs: Switch to webp, fix some sections (#514) Switches to webp and fixes some typos/poor wording.
2021-06-22 02:53:25 +00:00
<img src="../../../assets/screenshots/process/process_tree.webp" alt="A picture of tree mode in a process widget."/>
docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
</figure>
A process in tree mode can also be "collapsed", hiding its children and any descendants, using either the ++minus++ or ++plus++ keys, or double clicking on an entry.
Lastly, note that in tree mode, processes cannot be grouped together due to the behaviour of the two modes somewhat clashing.
### Full command
You can show the full command instead of just the process name by pressing ++P++.
<figure>
docs: Switch to webp, fix some sections (#514) Switches to webp and fixes some typos/poor wording.
2021-06-22 02:53:25 +00:00
<img src="../../../assets/screenshots/process/process_full.webp" alt="A picture of a process widget using full commands."/>
docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
</figure>
### Search
Pressing ++slash++ or ++ctrl+f++ will open up the search sub-widget. By default, just typing in something will search by the process name.
<figure>
docs: Switch to webp, fix some sections (#514) Switches to webp and fixes some typos/poor wording.
2021-06-22 02:53:25 +00:00
<img src="../../../assets/screenshots/process/search/search.webp" alt="A picture of searching for a process with a simple search."/>
docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
</figure>
This search can be further enhanced by matching by case, matching the entire word, or by regex.
<figure>
docs: Switch to webp, fix some sections (#514) Switches to webp and fixes some typos/poor wording.
2021-06-22 02:53:25 +00:00
<img src="../../../assets/screenshots/process/search/regex.webp" alt="A picture of searching for a process with a search condition that uses regex."/>
docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
</figure>
We are able to also search for multiple things/conditions.
<figure>
docs: Switch to webp, fix some sections (#514) Switches to webp and fixes some typos/poor wording.
2021-06-22 02:53:25 +00:00
<img src="../../../assets/screenshots/process/search/or.webp" alt="A picture of searching for a process with a search condition that uses the or operator."/>
docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
</figure>
And if our search uses a keyword, we need to use quotation marks around the term to properly search it.
<figure>
docs: Switch to webp, fix some sections (#514) Switches to webp and fixes some typos/poor wording.
2021-06-22 02:53:25 +00:00
<img src="../../../assets/screenshots/process/search/quotes.webp" alt="A picture of searching for a process with a search condition that needs quotation marks."/>
docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
</figure>
Lastly, we can refine our search even further based on the other columns, like PID, CPU usage, etc., as well as grouping together conditions.
<figure>
docs: Switch to webp, fix some sections (#514) Switches to webp and fixes some typos/poor wording.
2021-06-22 02:53:25 +00:00
<img src="../../../assets/screenshots/process/search/cpu.webp" alt="A picture of searching for a process with a search condition that uses the CPU keyword."/>
docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
</figure>
#### Keywords
Note all keywords are case-insensitive. To search for a process/command that collides with a keyword, surround the term with quotes (e.x. `"cpu"`).
| Keywords | Example | Description |
| ------------------------ | ------------------------------------- | ------------------------------------------------------------------------------- |
| | `btm` | Matches by process or command name; supports regex |
| `pid` | `pid=1044` | Matches by PID; supports regex |
| `cpu` <br/> `cpu%` | `cpu > 0.5` | Matches the CPU column; supports comparison operators |
| `memb` | `memb > 1000 b` | Matches the memory column in terms of bytes; supports comparison operators |
| `mem` <br/> `mem%` | `mem < 0.5` | Matches the memory column in terms of percent; supports comparison operators |
| `read` <br/> `r/s` | `read = 1 mb` | Matches the read/s column in terms of bytes; supports comparison operators |
| `write` <br/> `w/s` | `write >= 1 kb` | Matches the write/s column in terms of bytes; supports comparison operators |
| `tread` <br/> `t.read` | `tread <= 1024 gb` | Matches he total read column in terms of bytes; supports comparison operators |
| `twrite` <br/> `t.write` | `twrite > 1024 tb` | Matches the total write column in terms of bytes; supports comparison operators |
| `user` | `user=root` | Matches by user; supports regex |
| `state` | `state=running` | Matches by state; supports regex |
| `()` | `(<COND 1> AND <COND 2>) OR <COND 3>` | Group together a condition |
#### Comparison operators
| Keywords | Description |
| -------- | -------------------------------------------------------------- |
| `=` | Checks if the values are equal |
| `>` | Checks if the left value is strictly greater than the right |
| `<` | Checks if the left value is strictly less than the right |
| `>=` | Checks if the left value is greater than or equal to the right |
| `<=` | Checks if the left value is less than or equal to the right |
#### Logical operators
Note all operators are case-insensitive, and the `and` operator takes precedence over the `or` operator.
| Keywords | Usage | Description |
| ------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------------------------- |
| `and` <br/> `&&` <br/> `<Space>` | `<COND 1> and <COND 2>` <br/> `<COND 1> && <COND 2>` <br/> `<COND 1> <COND 2>` | Requires both conditions to be true to match |
| `or` <br/> <code>&#124;&#124;</code> | `<COND 1> or <COND 2>` <br/> `<COND 1> &#124;&#124; <COND 2>` | Requires at least one condition to be true to match |
#### Units
All units are case-insensitive.
| Keywords | Description |
| -------- | ----------- |
| `B` | Bytes |
| `KB` | Kilobytes |
| `MB` | Megabytes |
| `GB` | Gigabytes |
| `TB` | Terabytes |
| `KiB` | Kibibytes |
| `MiB` | Mebibytes |
| `GiB` | Gibibytes |
| `TiB` | Tebibytes |
## Key bindings
Note that key bindings are generally case-sensitive.
### Process table
| Binding | Action |
| ---------------------- | ---------------------------------------------------------------- |
| ++up++ , ++k++ | Move up within a widget |
| ++down++ , ++j++ | Move down within a widget |
| ++g+g++ , ++home++ | Jump to the first entry in the table |
| ++G++ , ++end++ | Jump to the last entry in the table |
feature: add F9 as an alternative process kill key (#518) Adds F9 as an alternative kill shortcut to dd.
2021-06-23 00:34:00 +00:00
| ++d+d++ , ++f9++ | Send a kill signal to the selected process |
docs: migrate documentation over to mkdocs (#506) A large migration of documentation over to mkdocs, and some rewrites. Some stuff (install information, basic supported systems, contributors, thanks) are still staying in README.md, and CONTRIBUTING.md is essentially duplicated right now. However, stuff like configuration and key/mouse bindings are now moved to mkdocs. Some parts are still a bit WIP - it is definitely not done (documentation never seems to be...). However, it should be "good enough" for now, and I'm much happier working with the documentation in this form than trying to scroll through a giant endless README.md file. It also works much better for adding new documentation.
2021-06-21 05:40:58 +00:00
| ++c++ | Sort by CPU usage, press again to reverse sorting order |
| ++m++ | Sort by memory usage, press again to reverse sorting order |
| ++p++ | Sort by PID name, press again to reverse sorting order |
| ++n++ | Sort by process name, press again to reverse sorting order |
| ++tab++ | Toggle grouping processes with the same name |
| ++P++ | Toggle between showing the full command or just the process name |
| ++ctrl+f++ , ++slash++ | Toggle showing the search sub-widget |
| ++s++ , ++f6++ | Toggle showing the sort sub-widget |
| ++I++ | Invert the current sort |
| ++"%"++ | Toggle between values and percentages for memory usage |
| ++t++ , ++f5++ | Toggle tree mode |
### Sort sub-widget
| Binding | Action |
| ------------------ | ------------------------------------- |
| ++up++ , ++k++ | Move up within a widget |
| ++down++ , ++j++ | Move down within a widget |
| ++g+g++ , ++home++ | Jump to the first entry in the table |
| ++G++ , ++end++ | Jump to the last entry in the table |
| ++esc++ | Close the sort sub-widget |
| ++enter++ | Sorts the corresponding process table |
### Search sub-widget
| Binding | Action |
| ------------------------------------- | -------------------------------------------- |
| ++left++ <br/> ++h++ <br/> ++alt+h++ | Moves the cursor left |
| ++right++ <br/> ++l++ <br/> ++alt+l++ | Moves the cursor right |
| ++tab++ | Toggle between searching by PID or name |
| ++esc++ | Close the search widget (retains the filter) |
| ++ctrl+a++ | Skip to the start of the search query |
| ++ctrl+e++ | Skip to the end of the search query |
| ++ctrl+u++ | Clear the current search query |
| ++ctrl+w++ | Delete a word behind the cursor |
| ++ctrl+h++ | Delete the character behind the cursor |
| ++backspace++ | Delete the character behind the cursor |
| ++delete++ | Delete the character at the cursor |
| ++alt+c++ , ++f1++ | Toggle matching case |
| ++alt+w++ , ++f2++ | Toggle matching the entire word |
| ++alt+r++ , ++f3++ | Toggle using regex |
## Mouse bindings
### Process table
| Binding | Action |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ++"Scroll"++ | Selects a CPU thread/average to show in the graph |
| ++lbutton++ | Table header: Sorts/reverse sorts the table by the column <br/> Table entry: Selects an entry in the table, if in tree mode, collapses/expands the entry's children |
### Sort sub-widget
| Binding | Action |
| ----------- | ----------------------------- |
| ++lbutton++ | Selects an entry in the table |
Reference in a new issue Copy permalink