From 395aa81c2aeb7f33c362c14c9328f3fd54c4aecc Mon Sep 17 00:00:00 2001 From: Ellie Huxtable Date: Wed, 21 Jun 2023 09:14:55 +0100 Subject: Revamp getting started guide (#1065) We were lacking some docs here really. Walk new users through getting installed and signed up! Coming next - Common config (how to disable the up arrow lol) - Troubleshooting - Community config/integrations --- docs/docs/advanced-install.md | 161 +++++++++++++++++++++++++++++ docs/docs/guide/index.md | 156 ++++++++++++++++++++++++++++ docs/docs/index.md | 229 ------------------------------------------ docs/docusaurus.config.js | 2 +- docs/src/pages/index.js | 2 +- install.sh | 1 - 6 files changed, 319 insertions(+), 232 deletions(-) create mode 100644 docs/docs/advanced-install.md create mode 100644 docs/docs/guide/index.md delete mode 100644 docs/docs/index.md diff --git a/docs/docs/advanced-install.md b/docs/docs/advanced-install.md new file mode 100644 index 00000000..f9ff719f --- /dev/null +++ b/docs/docs/advanced-install.md @@ -0,0 +1,161 @@ +--- +title: Advanced Install +--- +Generally, we recommend using our install script. It ensures you use the most +up-to-date Atuin, and that your shell plugin is correctly setup. It will prefer +the system package manager wherever necessary! + +However, I totally understand if you'd rather do things yourself and not run a +script from the internet. If so, follow on! + +## Install Atuin + +Atuin is in a number of package repositories! Please choose whichever works best for you. + +### With cargo + +It's best to use [rustup](https://rustup.rs/) to get setup with a Rust +toolchain, then you can run: + +``` +cargo install atuin +``` + +And then follow [the shell setup](#shell-plugin) + +### Homebrew + +``` +brew install atuin +``` + +And then follow [the shell setup](#shell-plugin) + +### MacPorts + +Atuin is also available in [MacPorts](https://ports.macports.org/port/atuin/) + +``` +sudo port install atuin +``` + +And then follow [the shell setup](#shell-plugin) + +### Nix + +This repository is a flake, and can be installed using `nix profile`: + +``` +nix profile install "github:ellie/atuin" +``` + +Atuin is also available in [nixpkgs](https://github.com/NixOS/nixpkgs): + +``` +nix-env -f '' -iA atuin +``` + +And then follow [the shell setup](#shell-plugin) +### Pacman + +Atuin is available in the Arch Linux [community repository](https://archlinux.org/packages/community/x86_64/atuin/): + +``` +pacman -S atuin +``` + +And then follow [the shell setup](#shell-plugin) + +### Termux + +Atuin is available in the Termux package repository: + +``` +pkg install atuin +``` + +And then follow [the shell setup](#shell-plugin) + +### From source + +Note: Atuin builds on the latest stable version of Rust, and we make no +promises regarding older versions. We recommend using rustup. + +``` +git clone https://github.com/ellie/atuin.git +cd atuin/atuin +cargo install --path . +``` + +## Shell plugin + +Once the binary is installed, the shell plugin requires installing. If you use +the install script, this should all be done for you! After installing, remember to restart your shell. + +### zsh + +``` +echo 'eval "$(atuin init zsh)"' >> ~/.zshrc +``` + +#### Zinit + +```sh +zinit load ellie/atuin +``` + +#### Antigen + +```sh +antigen bundle ellie/atuin@main +``` + +### bash + +We need to setup some hooks, so first install bash-preexec: + +``` +curl https://raw.githubusercontent.com/rcaloras/bash-preexec/master/bash-preexec.sh -o ~/.bash-preexec.sh +echo '[[ -f ~/.bash-preexec.sh ]] && source ~/.bash-preexec.sh' >> ~/.bashrc +``` + +Then setup Atuin + +``` +echo 'eval "$(atuin init bash)"' >> ~/.bashrc +``` + +**PLEASE NOTE** + +bash-preexec currently has an issue where it will stop honoring `ignorespace`. While Atuin will ignore commands prefixed with whitespace, they may still end up in your bash history. Please check your configuration! All other shells do not have this issue. + +### fish + +Add + +``` +atuin init fish | source +``` + +to your `is-interactive` block in your `~/.config/fish/config.fish` file + +### Fig + +Install `atuin` shell plugin in zsh, bash, or fish with [Fig](https://fig.io) in one click. + + + +### Nushell + +Run in *Nushell*: + +``` +mkdir ~/.local/share/atuin/ +atuin init nu | save ~/.local/share/atuin/init.nu +``` + +Add to `config.nu`: + +``` +source ~/.local/share/atuin/init.nu +``` diff --git a/docs/docs/guide/index.md b/docs/docs/guide/index.md new file mode 100644 index 00000000..f605f520 --- /dev/null +++ b/docs/docs/guide/index.md @@ -0,0 +1,156 @@ +--- +title: Getting Started +id: index +sidebar_position: 1 +--- + +Atuin replaces your existing shell history with a SQLite database, and records +additional context for your commands. With this context, Atuin gives you faster +and better search of your shell history! + +Additionally, Atuin (optionally) syncs your shell history between all of your +machines! Fully end-to-end encrypted, of course. + +You may use either the server I host, or host your own! Or just don't use sync +at all. As all history sync is encrypted, I couldn't access your data even if I +wanted to. And I **really** don't want to. + +If you have any problems, please open an [issue](https://github.com/ellie/atuin/issues) or get in touch on our [Discord](https://discord.gg/Fq8bJSKPHh)! + +## Supported Shells + +- zsh +- bash +- fish +- nushell + +# Quickstart + +Please do try and read this guide, but if you're in a hurry and want to get started quickly: + +``` +bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) + +atuin register -u -e +atuin import auto +atuin sync +``` + +# Full Guide + +Let's get started! First up, you will want to install Atuin. We have an install +script which handles most of the commonly used platforms and package managers: + +``` +bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) +``` + +The script will install the binary and attempt to configure your shell. Atuin +uses a shell plugin to ensure that we capture new shell history. But for older +history, you will need to import it + +This will import the history for your current shell: +``` +atuin import auto +``` + +Alternatively, you can specify the shell like so: + +``` +atuin import bash +atuin import zsh # etc +``` + +## Register + +At this point, you have Atuin storing and searching your shell history! But it +isn't syncing it just yet. To do so, you'll need to register with the sync +server. All of your history is fully end-to-end encrypted, so there are no +risks of the server snooping on you. + +Note: if you already have an account and wish to sync with an additional +machine, follow the [below guide](#syncing-additional-machines) instead. + +``` +atuin register -u -e +``` + +After registration, Atuin will generate an encryption key for you and store it +locally. This is needed for logging in to other machines, and can be seen with + +``` +atuin key +``` + +Please **never** share this key with anyone! The Atuin developers will never +ask you for your key, your password, or the contents of your Atuin directory. + +If you lose your key, we can do nothing to help you. We recommend you store +this somewhere safe, such as in a password manager. + +## First sync +By default, Atuin will sync your history once per hour. This can be +[configured](/docs/config#sync_frequency). + +To run a sync manually, please run + +``` +atuin sync +``` + +Atuin tries to be smart with a sync, and not waste data transfer. However, if +you are seeing some missing data, please try running + +``` +atuin sync -f +``` + +This triggers a full sync, which may take longer as it works through historical data. + +## Syncing additional machines + +When only signed in on one machine, Atuin sync operates as a backup. This is +pretty useful by itself, but syncing multiple machines is where the magic +happens. + +First, ensure you are [registered with the sync server](#register) and make a +note of your key. You can see this with `atuin key`. + +Then, install Atuin on a new machine. Once installed, login with + +``` +atuin login -u +``` + +You will be prompted for your password, and for your key. + +Syncing will happen automatically in the background, but you may wish to run it manually with + +``` +atuin sync +``` + +Or, if you see missing data, force a full sync with: + +``` +atuin sync -f +``` + +## Opt-in to activity graph +Alongside the hosted Atuin server, there is also a service which generates +activity graphs for your shell history! These are inspired by the GitHub graph. + +For example, here is mine: + +![Activity Graph Example](https://api.atuin.sh/img/ellie.png?token=0722830c382b42777bdb652da5b71efb61d8d387) + +If you wish to get your own, after signing up for the sync server, run this + +``` +curl https://api.atuin.sh/enable -d $(cat ~/.local/share/atuin/session) +``` + +The response includes the URL to your graph. Feel free to share and/or embed +this URL, the token is _not_ a secret, and simply prevents user enumeration. + + diff --git a/docs/docs/index.md b/docs/docs/index.md deleted file mode 100644 index 19f92eaa..00000000 --- a/docs/docs/index.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: Getting Started -sidebar_position: 1 ---- - -Atuin replaces your existing shell history with a SQLite database, and records -additional context for your commands. Additionally, it provides optional and -_fully encrypted_ synchronisation of your history between machines, via an Atuin -server. - -You may use either the server I host, or host your own! Or just don't use sync -at all. As all history sync is encrypted, I couldn't access your data even if -I wanted to. And I **really** don't want to. - -## Supported Shells - -- zsh -- bash -- fish -- nushell - -## Community - -Atuin has a community Discord, available [here](https://discord.gg/Fq8bJSKPHh) - -# Quickstart - -## With the default sync server - -This will sign you up for the default sync server, hosted by me. Everything is end-to-end encrypted, so your secrets are safe! - -Read more below for offline-only usage, or for hosting your own server. - -``` -bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) - -atuin register -u -e -p -atuin import auto -atuin sync -``` - -Then restart your shell! - -### Opt-in to activity graph -Alongside the hosted Atuin server, there is also a service which generates activity graphs for your shell history! These are inspired by the GitHub graph. - -For example, here is mine: - -![Activity Graph Example](/img/activity-graph-example.png) - -If you wish to get your own, after signing up for the sync server, run this - -``` -curl https://api.atuin.sh/enable -d $(cat ~/.local/share/atuin/session) -``` - -The response includes the URL to your graph. Feel free to share and/or embed this URL, the token is _not_ a secret, and simply prevents user enumeration. - -## Offline only (no sync) - -``` -bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) - -atuin import auto -``` - -Then restart your shell! - -## Install - -### Script (recommended) - -The install script will help you through the setup, ensuring your shell is -properly configured. It will also use one of the below methods, preferring the -system package manager where possible (pacman, homebrew, etc etc). - -``` -# do not run this as root, root will be asked for if required -bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh) -``` - -And then follow [the shell setup](#shell-plugin) - -### With cargo - -It's best to use [rustup](https://rustup.rs/) to get setup with a Rust -toolchain, then you can run: - -``` -cargo install atuin -``` - -And then follow [the shell setup](#shell-plugin) - -### Homebrew - -``` -brew install atuin -``` - -And then follow [the shell setup](#shell-plugin) - -### MacPorts - -Atuin is also available in [MacPorts](https://ports.macports.org/port/atuin/) - -``` -sudo port install atuin -``` - -And then follow [the shell setup](#shell-plugin) - -### Nix - -This repository is a flake, and can be installed using `nix profile`: - -``` -nix profile install "github:ellie/atuin" -``` - -Atuin is also available in [nixpkgs](https://github.com/NixOS/nixpkgs): - -``` -nix-env -f '' -iA atuin -``` - -And then follow [the shell setup](#shell-plugin) -### Pacman - -Atuin is available in the Arch Linux [community repository](https://archlinux.org/packages/community/x86_64/atuin/): - -``` -pacman -S atuin -``` - -And then follow [the shell setup](#shell-plugin) - -### Termux - -Atuin is available in the Termux package repository: - -``` -pkg install atuin -``` - -And then follow [the shell setup](#shell-plugin) - -### From source - -``` -git clone https://github.com/ellie/atuin.git -cd atuin/atuin -cargo install --path . -``` - -And then follow [the shell setup](#shell-plugin) - -## Shell plugin - -Once the binary is installed, the shell plugin requires installing. If you use -the install script, this should all be done for you! After installing, remember to restart your shell. - -### zsh - -``` -echo 'eval "$(atuin init zsh)"' >> ~/.zshrc -``` - -#### Zinit - -```sh -zinit load ellie/atuin -``` - -#### Antigen - -```sh -antigen bundle ellie/atuin@main -``` - -### bash - -We need to setup some hooks, so first install bash-preexec: - -``` -curl https://raw.githubusercontent.com/rcaloras/bash-preexec/master/bash-preexec.sh -o ~/.bash-preexec.sh -echo '[[ -f ~/.bash-preexec.sh ]] && source ~/.bash-preexec.sh' >> ~/.bashrc -``` - -Then setup Atuin - -``` -echo 'eval "$(atuin init bash)"' >> ~/.bashrc -``` - -**PLEASE NOTE** - -bash-preexec currently has an issue where it will stop honoring `ignorespace`. While Atuin will ignore commands prefixed with whitespace, they may still end up in your bash history. Please check your configuration! All other shells do not have this issue. - -### fish - -Add - -``` -atuin init fish | source -``` - -to your `is-interactive` block in your `~/.config/fish/config.fish` file - -### Fig - -Install `atuin` shell plugin in zsh, bash, or fish with [Fig](https://fig.io) in one click. - - - -### Nushell - -Run in *Nushell*: - -``` -mkdir ~/.local/share/atuin/ -atuin init nu | save ~/.local/share/atuin/init.nu -``` - -Add to `config.nu`: - -``` -source ~/.local/share/atuin/init.nu -``` diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index ad70c001..c087971c 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -70,7 +70,7 @@ const config = { items: [ { type: 'doc', - docId: 'index', + docId: 'guide/index', position: 'left', label: 'Docs', }, diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js index cd983759..de42742b 100644 --- a/docs/src/pages/index.js +++ b/docs/src/pages/index.js @@ -20,7 +20,7 @@ function HomepageHeader() {
+ to="/docs/guide"> Get Started
diff --git a/install.sh b/install.sh index ef8b9200..0d306464 100755 --- a/install.sh +++ b/install.sh @@ -105,7 +105,6 @@ __atuin_install_mac(){ if command -v brew &> /dev/null then echo "Installing with brew" - brew tap ellie/atuin brew install atuin else echo "Could not find brew, installing with Cargo" -- cgit v1.3.1