From 156893d774b4da5b541fdbb08428f9ec392949a0 Mon Sep 17 00:00:00 2001 From: Ellie Huxtable Date: Sun, 25 Apr 2021 18:21:52 +0100 Subject: Update docs, unify on SQLx, bugfixes (#40) * Begin moving to sqlx for local too * Stupid scanners should just have a nice cup of tea Random internet shit searching for /.env or whatever * Remove diesel and rusqlite fully --- docs/config.md | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/import.md | 27 ++++++++++++++++ docs/list.md | 11 +++++++ docs/search.md | 39 +++++++++++++++++++++++ docs/stats.md | 36 +++++++++++++++++++++ docs/sync.md | 55 ++++++++++++++++++++++++++++++++ 6 files changed, 267 insertions(+) create mode 100644 docs/config.md create mode 100644 docs/import.md create mode 100644 docs/list.md create mode 100644 docs/search.md create mode 100644 docs/stats.md create mode 100644 docs/sync.md (limited to 'docs') diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 000000000..7c042251c --- /dev/null +++ b/docs/config.md @@ -0,0 +1,99 @@ +# Config + +Atuin maintains two configuration files, stored in `~/.config/atuin/`. We store +data in `~/.local/share/atuin` (unless overridden by XDG\_\*). + +You can also change the path to the configuration directory by setting +`ATUIN_CONFIG_DIR`. For example + +``` +export ATUIN_CONFIG_DIR = /home/ellie/.atuin +``` + +## Client config + +``` +~/.config/atuin/config.toml +``` + +The client runs on a user's machine, and unless you're running a server, this +is what you care about. + +See [config.toml](../atuin-client/config.toml) for an example + +### `dialect` + +This configures how the [stats](stats.md) command parses dates. It has two +possible values + +``` +dialect = "uk" +``` + +or + +``` +dialect = "us" +``` + +and defaults to "us". + +### `auto_sync` + +Configures whether or not to automatically sync, when logged in. Defaults to +true + +``` +auto_sync = true/false +``` + +### `sync_address` + +The address of the server to sync with! Defaults to `https://api.atuin.sh`. + +``` +sync_address = "https://api.atuin.sh" +``` + +### `sync_frequency` + +How often to automatically sync with the server. This can be given in a +"human readable" format. For example, `10s`, `20m`, `1h`, etc. Defaults to `1h`. + +If set to `0`, Atuin will sync after every command. Some servers may potentially +rate limit, which won't cause any issues. + +``` +sync_frequency = "1h" +``` + +### `db_path` + +The path to the Atuin SQlite database. Defaults to +`~/.local/share/atuin/history.db`. + +``` +db_path = "~/.history.db" +``` + +### `key_path` + +The path to the Atuin encryption key. Defaults to +`~/.local/share/atuin/key`. + +``` +key = "~/.atuin-key" +``` + +### `session_path` + +The path to the Atuin server session file. Defaults to +`~/.local/share/atuin/session`. This is essentially just an API token + +``` +key = "~/.atuin-session" +``` + +## Server config + +`// TODO` diff --git a/docs/import.md b/docs/import.md new file mode 100644 index 000000000..9fc0580e9 --- /dev/null +++ b/docs/import.md @@ -0,0 +1,27 @@ +# `atuin import` + +Atuin can import your history from your "old" history file + +`atuin import auto` will attempt to figure out your shell (via \$SHELL) and run +the correct importer + +Unfortunately these older files do not store as much information as Atuin does, +so not all features are available with imported data. + +# zsh + +``` +atuin import zsh +``` + +If you've set HISTFILE, this should be picked up! If not, try + +``` +HISTFILE=/path/to/history/file atuin import zsh +``` + +This supports both the simple and extended format + +# bash + +TODO diff --git a/docs/list.md b/docs/list.md new file mode 100644 index 000000000..1b04a5b8b --- /dev/null +++ b/docs/list.md @@ -0,0 +1,11 @@ +# Listing history + +``` +atuin history list +``` + +| Arg | Description | +| -------------- | ----------------------------------------------------------------------------- | +| `--cwd/-c` | The directory to list history for (default: all dirs) | +| `--session/-s` | Enable listing history for the current session only (default: false) | +| `--human/-h` | Use human-readable formatting for the timestamp and duration (default: false) | diff --git a/docs/search.md b/docs/search.md new file mode 100644 index 000000000..b1034007b --- /dev/null +++ b/docs/search.md @@ -0,0 +1,39 @@ +# `atuin search` + +``` +atuin search +``` + +Atuin search also supports wildcards, with either the `*` or `%` character. By +default, a prefix search is performed (ie, all queries are automatically +appended with a wildcard. + +| Arg | Description | +| ------------------ | ----------------------------------------------------------------------------- | +| `--cwd/-c` | The directory to list history for (default: all dirs) | +| `--exclude-cwd` | Do not include commands that ran in this directory (default: none) | +| `--exit/-e` | Filter by exit code (default: none) | +| `--exclude-exit` | Do not include commands that exited with this value (default: none) | +| `--before` | Only include commands ran before this time(default: none) | +| `--after` | Only include commands ran after this time(default: none) | +| `--interactive/-i` | Open the interactive search UI (default: false) | +| `--human/-h` | Use human-readable formatting for the timestamp and duration (default: false) | + +## Examples + +``` +# Open the interactive search TUI +atuin search -i + +# Open the interactive search TUI preloaded with a query +atuin search -i atuin + +# Search for all commands, beginning with cargo, that exited successfully +atuin search --exit 0 cargo + +# Search for all commands, that failed, from the current dir, and were ran before April 1st 2021 +atuin search --exclude-exit 0 --before 01/04/2021 --cwd . + +# Search for all commands, beginning with cargo, that exited successfully, and were ran after yesterday at 3pm +atuin search --exit 0 --after "yesterday 3pm" cargo +``` diff --git a/docs/stats.md b/docs/stats.md new file mode 100644 index 000000000..9c08ce199 --- /dev/null +++ b/docs/stats.md @@ -0,0 +1,36 @@ +# `atuin stats` + +Atuin can also calculate stats based on your history - this is currently a +little basic, but more features to come + +``` +$ atuin stats day last friday + ++---------------------+------------+ +| Statistic | Value | ++---------------------+------------+ +| Most used command | git status | ++---------------------+------------+ +| Commands ran | 450 | ++---------------------+------------+ +| Unique commands ran | 213 | ++---------------------+------------+ + +$ atuin stats day 01/01/21 # also accepts absolute dates +``` + +It can also calculate statistics for all of known history: + +``` +$ atuin stats all + ++---------------------+-------+ +| Statistic | Value | ++---------------------+-------+ +| Most used command | ls | ++---------------------+-------+ +| Commands ran | 8190 | ++---------------------+-------+ +| Unique commands ran | 2996 | ++---------------------+-------+ +``` diff --git a/docs/sync.md b/docs/sync.md new file mode 100644 index 000000000..785105267 --- /dev/null +++ b/docs/sync.md @@ -0,0 +1,55 @@ +# `atuin sync` + +Atuin can backup your history to a server, and use this to ensure multiple +machines have the same shell history. This is all encrypted end-to-end, so the +server operator can _never_ see your data! + +Anyone can host a server (try `atuin server start`, more docs to follow), but I +host one at https://api.atuin.sh. This is the default server address, which can +be changed in the [config](docs/config.md). Again, I _cannot_ see your data, and +do not want to. + +## Sync frequency + +Syncing will happen automatically, unless configured otherwise. The sync +frequency is configurable in [config](docs/config.md) + +## Sync + +You can manually trigger a sync with `atuin sync` + +## Register + +Register for a sync account with + +``` +atuin register -u -e -p +``` + +Usernames must be unique, and emails shall only be used for important +notifications (security breaches, changes to service, etc). + +Upon success, you are also logged in :) Syncing should happen automatically from +here! + +## Key + +As all your data is encrypted, Atuin generates a key for you. It's stored in the +Atuin data directory (`~/.local/share/atuin` on Linux). + +You can also get this with + +``` +atuin key +``` + +Never share this with anyone! + +## Login + +If you want to login to a new machine, you will require your encryption key +(`atuin key`). + +``` +atuin login -u -p -k +``` -- cgit v1.2.3