diff --git a/astro.config.mjs b/astro.config.mjs index 2d59b72..89e2f48 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -41,6 +41,10 @@ export default defineConfig({ label: 'Configuration', autogenerate: { directory: 'configuration' }, }, + { + label: 'Reference', + autogenerate: { directory: 'reference' }, + }, { label: 'Self hosting', items: [ diff --git a/src/content/docs/guides/example.md b/src/content/docs/guides/example.md deleted file mode 100644 index ebd0f3b..0000000 --- a/src/content/docs/guides/example.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Example Guide -description: A guide in my new Starlight docs site. ---- - -Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. -Writing a good guide requires thinking about what your users are trying to do. - -## Further reading - -- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/src/content/docs/reference/gen-completions.mdx b/src/content/docs/reference/gen-completions.mdx new file mode 100644 index 0000000..88f1837 --- /dev/null +++ b/src/content/docs/reference/gen-completions.mdx @@ -0,0 +1,21 @@ +--- +title: gen-completions +--- + +[Shell completions](https://en.wikipedia.org/wiki/Command-line_completion) for Atuin can be generated by specifying the output directory and desired shell via `gen-completions` subcommand. + +``` +$ atuin gen-completions --shell bash --out-dir $HOME + +Shell completion for BASH is generated in "/home/user" +``` + +Possible values for the `--shell` argument are the following: + +- `bash` +- `fish` +- `zsh` +- `powershell` +- `elvish` + +Also, see the [supported shells](https://atuin.sh/docs/#supported-shells). diff --git a/src/content/docs/reference/import.mdx b/src/content/docs/reference/import.mdx new file mode 100644 index 0000000..1961189 --- /dev/null +++ b/src/content/docs/reference/import.mdx @@ -0,0 +1,33 @@ +--- +title: import +--- + +# `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 + +``` +atuin import bash +``` diff --git a/src/content/docs/reference/list.mdx b/src/content/docs/reference/list.mdx new file mode 100644 index 0000000..7cac3ec --- /dev/null +++ b/src/content/docs/reference/list.mdx @@ -0,0 +1,33 @@ +--- +title: history list +--- + +# `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` | Use human-readable formatting for the timestamp and duration (default: false) | +| `--cmd-only` | Show only the text of the command (default: false) | +| `--reverse` | Reverse the order of the output (default: false) | +| `--format` | Specify the formatting of a command (see below) | +| `--print0` | Terminate the output with a null, for better multiline support | + + +## Format + +Customize the output of `history list` + +Example + +``` +atuin history list --format "{time} - {duration} - {command}" +``` + +Supported variables + +``` +{command}, {directory}, {duration}, {user}, {host} and {time} +``` diff --git a/src/content/docs/reference/search.md b/src/content/docs/reference/search.md new file mode 100644 index 0000000..14eeedf --- /dev/null +++ b/src/content/docs/reference/search.md @@ -0,0 +1,67 @@ +--- +title: search +--- + +Atuin search 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` | Use human-readable formatting for the timestamp and duration (default: false) | +| `--limit` | Limit the number of results (default: none) | +| `--offset` | Offset from the start of the results (default: none) | +| `--delete` | Delete history matching this query | +| `--delete-it-all` | Delete all shell history | +| `--reverse` | Reverse order of search results, oldest first | +| `--format`/`-f` | Available variables: {command}, {directory}, {duration}, {user}, {host}, {time}, {exit} and {relativetime}. Example: --format "{time} - [{duration}] - {directory}$\t{command}" | +| `--inline-height` | Set the maximum number of lines Atuin's interface should take up | +| `--help`/`-h` | Print help | + +## `atuin search -i` + +Atuin's interactive search TUI allows you to fuzzy search through your history. + +![compact](https://user-images.githubusercontent.com/1710904/161623659-4fec047f-ea4b-471c-9581-861d2eb701a9.png) + +You can replay the `nth` command with `alt + #` where `#` is the line number of the command you would like to replay. + +Note: This is not yet supported on macOS. + +## 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 + +# Delete all commands, beginning with cargo, that exited successfully, and were ran after yesterday at 3pm +atuin search --delete --exit 0 --after "yesterday 3pm" cargo + +# Search for a command beginning with cargo, return exactly one result. +atuin search --limit 1 cargo + +# Search for a single result for a command beginning with cargo, skipping (offsetting) one result +atuin search --offset 1 --limit 1 cargo + +# Find the oldest cargo command +atuin search --limit 1 --reverse cargo +``` diff --git a/src/content/docs/reference/stats.mdx b/src/content/docs/reference/stats.mdx new file mode 100644 index 0000000..2dff310 --- /dev/null +++ b/src/content/docs/reference/stats.mdx @@ -0,0 +1,52 @@ +--- +title: stats +--- + +Atuin can also calculate stats based on your history - this is currently a +little basic, but more features to come. + +## 1-day stats + +You provide the starting point, and Atuin computes the stats for 24h from that point. +Date parsing is provided by `interim`, which supports different formats +for full or relative dates. Certain formats rely on the dialect option in your +[configuration](../../docs/config/config.md#dialect) to differentiate day from month. +Refer to [the module's documentation](https://docs.rs/interim/0.1.0/interim/#supported-formats) for more details on the supported date formats. + +``` +$ atuin stats last friday + ++---------------------+------------+ +| Statistic | Value | ++---------------------+------------+ +| Most used command | git status | ++---------------------+------------+ +| Commands ran | 450 | ++---------------------+------------+ +| Unique commands ran | 213 | ++---------------------+------------+ + +# A few more examples: +$ atuin stats 2018-04-01 +$ atuin stats April 1 +$ atuin stats 01/04/22 +$ atuin stats last thursday 3pm # between last thursday 3:00pm and the following friday 3:00pm +``` + +## Full history stats + +``` +$ atuin stats +# or +$ atuin stats all + ++---------------------+-------+ +| Statistic | Value | ++---------------------+-------+ +| Most used command | ls | ++---------------------+-------+ +| Commands ran | 8190 | ++---------------------+-------+ +| Unique commands ran | 2996 | ++---------------------+-------+ +``` diff --git a/src/content/docs/reference/sync.mdx b/src/content/docs/reference/sync.mdx new file mode 100644 index 0000000..cb6f782 --- /dev/null +++ b/src/content/docs/reference/sync.mdx @@ -0,0 +1,79 @@ +--- +title: sync +--- + +Atuin can back up 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/config.md#sync_address). 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/config.md#sync_frequency) + +## Sync + +You can manually trigger a sync with `atuin sync` + +## Register + +Register for a sync account with + +``` +atuin register -u -e -p +``` + +If you don't want to have your password be included in shell history, you can omit +the password flag and you will be prompted to provide it through stdin. + +Usernames must be unique and only contain alphanumerics or hyphens, +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! + +## Delete + +You can delete your sync account with + +``` +atuin account delete +``` + +This will remove your account and all synchronized history from the server. Local data will not be touched! + +## 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 log in to a new machine, you will require your encryption key +(`atuin key`). + +``` +atuin login -u -p -k +``` + +If you don't want to have your password be included in shell history, you can omit +the password flag and you will be prompted to provide it through stdin. + +## Logout + +``` +atuin logout +```