From 5ada5315d940038fcd83777b1e73797bbbada108 Mon Sep 17 00:00:00 2001
From: "Sean E. Russell" <ser@ser1.net>
Date: Thu, 23 Apr 2020 10:41:20 -0500
Subject: Fixes #92, configurable temps; help text & docs clean-up; versions
 are now built into binaries at compile time; clean up old extensions params;
 adds --list command; adds --write-config command; fixes bug in colorscheme
 loading; fixes bug in Colorschemes -- all had empty Name attrs; adds ability
 to list devices.

---
 README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 5b3ce0f..fd37437 100644
--- a/README.md
+++ b/README.md
@@ -127,12 +127,30 @@ Move `gotop` to somewhere in your `$PATH`.
 - click to select process
 - mouse wheel to scroll through processes
 
+### Config file
+
+Most command-line settings can be persisted into a configuration file. The config file is named `gotop.conf` and can be located in several places. The first place gotop will look is in the current directory; after this, the locations depend on the OS and distribution. On Linux using XDG, for instance, the home location of `~/.config/gotop/gotop.conf` is the second location. The last location is a system-wide global location, such as `/etc/gotop/gotop.conf`. The `-h` help command will print out all of the locations, in order. Command-line options override values in any config files, and only the first config file found is loaded.
+
+A configuration file can be created using the `--write-config` command-line argument. This will try to place the config file in the home config directory (the second location), but if it's unable to do so it'll write a file to the current directory.
+
+Config file changes can be made by combining command-line arguments with `--write-config`. For example, to persist the `solarized` theme, call:
+
+```
+gotop -c solarized --write-config
+```
+
 ### Colorschemes
 
 gotop ships with a few colorschemes which can be set with the `-c` flag followed by the name of one. You can find all the colorschemes in the [colorschemes folder](./colorschemes).
 
 To make a custom colorscheme, check out the [template](./colorschemes/template.go) for instructions and then use [default.json](./colorschemes/default.json) as a starter. Then put the file at `~/.config/gotop/<name>.json` and load it with `gotop -c <name>`. Colorschemes PR's are welcome!
 
+To list all built-in color schemes, call:
+
+```
+gotop --list colorschemes
+```
+
 ### Layouts
 
 gotop can parse and render layouts from a specification file.  The format is
@@ -206,6 +224,49 @@ and these are separated by spaces.
 Yes, you're clever enough to break the layout algorithm, but if you try to
 build massive edifices, you're in for disappointment.
 
+To list all built-in color schemes, call:
+
+```
+gotop --list layouts
+```
+
+### Device filtering
+
+Some devices have quite a number of data points; on OSX, for instance, there are dozens of temperature readings. These can be filtered through a configuration file.  There is no command-line argument for this filter.
+
+The list will grow, but for now the only device that supports filtering is the temperature widget.  The configuration entry is called `temperature`, and it contains an exact-match list of comma-separated values with no spaces.  To see the list of valid values, run gotop with the `--list devices` command.  Gotop will print out the type of device and the legal values.  For example, on Linux:
+
+```
+$ gotop --list devices
+Temperatures:
+        acpitz
+        nvme_composite
+        nvme_sensor1
+        nvme_sensor2
+        pch_cannonlake
+        coretemp_packageid0
+        coretemp_core0
+        coretemp_core1
+        coretemp_core2
+        coretemp_core3
+        ath10k_hwmon
+```
+You might then add the following line to the config file.  First, find where gotop looks for config files:
+```
+$ gotop -h | tail -n 6
+Colorschemes & layouts that are not built-in are searched for (in order) in:
+/home/USER/workspace/gotop.d/gotop, /home/USER/.config/gotop, /etc/xdg/gotop
+The first path in this list is always the cwd. The config file
+'gotop.config' can also reside in one of these directories.
+
+Log files are stored in /home/ser/.cache/gotop/errors.log
+```
+So you might use `/home/YOU/.config/gotop.conf`, and add (or modify) this line:
+```
+temperatures=acpitz,coretemp_core0,ath10k_hwmon
+```
+This will cause the temp widget to show only four of the eleven temps.
+
 ### CLI Options
 
 Run `gotop -h` to see the list of all command line options.
-- 
cgit v1.2.3