From cd70facdd22370d0501d612d9c27c8e179a54fb6 Mon Sep 17 00:00:00 2001 From: bretello Date: Sat, 5 Dec 2020 15:38:52 +0100 Subject: [PATCH] cleanup documentation --- README.md | 173 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 104 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 5955631..479be71 100644 --- a/README.md +++ b/README.md @@ -1,96 +1,131 @@ -# brethil's dotfiles # -A set of zsh dotfiles based on antigen and oh-my-zsh +# brethil's dotfiles -## Description ## +A set of zsh dotfiles based on antibody and oh-my-zsh -1. brethil_dotfile.sh: main file sourced by ~/.zshrc -2. aliases.sh: contains alias definitions (sources ~/.dotfiles_aliases) -3. functions.sh: contains function definitions (sources ~/.dotfiles_functions) -4. colors.sh: contains color definitions -5. install.sh: run to install brethil's dotfiles +## Description -## Installation ## -Copy the dotfiles folder to the location where you want to keep it and then run install: +├── README.md +├──────── Main files ──────── +│ ├── aliases.sh +│ │ └── aliases definitions (sources `~/.dotfiles_aliases`) +│ ├── colors.sh +│ │ └── ANSI color escapes +│ ├── functions.sh +│ │ └── contains function definitions (sources `~/.dotfiles_functions`) +│ ├── install.sh +│ │ └── main install script +│ └── brethil_dotfile.sh: This file should be sourced by your `.zshrc` +├──────── antibody plugins ──────── +│ ├── antibody_plugins_arch.txt +│ └── antibody_plugins.txt +├──────── oh-my-zsh themes ──────── +│ ├── brethil.zsh-theme +│ └── brethil-minimal.zsh-theme +├──────── Misc rc files──────── +│ ├── gitconfig +│ │ └── git configuration +│ ├── ackrc +│ │ └── `ack`'s rc: a grep-like text finder +│ ├── ipython +│ │   ├── profile_default +│ │   ├── ipython_config.py +│ │   ├── startup +│ │   ├── 11-autoreload.py +│ │   └── README +│ ├── my_configs.vim +│ │ └── vim (sourced by amix's vimrc) +│ ├── twilight256.vim +│ │ └── vim's colorscheme +│ └── pdbrc.py +│ . └── pdb++'s rc (a drop-in replacement for pdb) +├──────── Other ───────────── +├── check_for_update.sh +│ └── selfupdate script +└── useful_commands - $ cd dotfiles && bash install.sh +## Installation -Installs oh-my-zsh and sources aliases.sh, functions.sh and colors.sh, as well as installing -a a few utilities (see `install.sh`). + git clone https://git.decapod.one/brethil/dotfiles ~/.dotfiles + cd .dotfiles && bash install.sh A self-update mechanism is included. It asks for confirmation to pull the latest changes from the git repo every two weeks. This also updates the git-sourced repositories installed by the install script. The self-update routine can be called manually by calling -`dotfiles_selfupdate` (defined in `functions.sh`). + + dotfiles_selfupdate If you do not want to run the installer script, you can just add source `brethil_dotfile.sh` -in your .zshrc. This requires antigen installed. +in your `.zshrc`. This requires antibody installed. -### Installed ### +### Installed -0. antigen (zsh plugin manager) + oh-my-zsh - Two zsh themes: brethil and brethil-minimal. -1. amix's awesome vimrc (https://www.github.com/amix/vimrc). A quite nice vim rc. -2. byobu (wrapper/config for tmux, a screen multiplexer) -3. grc/ccze (output colorizers, color output of any command). Usage: +1. `antibody`: zsh plugin manager + - `oh-my-zsh` + - `oh-my-zsh` zsh themes: `brethil` and `brethil-minimal`. +2. (amix's awesome vimrc)[https://www.github.com/amix/vimrc]: A quite nice vim rc. +3. `byobu`: wrapper/config for tmux, a screen multiplexer +4. `grc`/`ccze`: output colorizers, can color the output of any command, usage: - $ grc cmd - $ cmd | ccze + grc + | ccze -4. bmon (bandwidth monitor, shows graphs for bandwith usage) -5. rmate remote for Textmate (can be called with `mate`/`rmate`) -6. mtr (my traceroute, traceroute+ping network utility) -7. htop (better top) +5. `bmon`: bandwidth monitor, shows graphs for bandwith usage +6. `mtr`: my traceroute, traceroute+ping network utility +7. `htop`: better top +### Available Functions -### Available Functions ### +0. `cheat`: show cheat sheet for commands using cheat.sh (`cheat `) +1. Quickly edit/reload profile (`esource`/`resource`) +2. `dockertags` list all tags for a given docker image +3. `color` to print colored text (see 3. in the Misc section): -0. `cheat`, show cheat sheet for commands using cheat.sh (`cheat commandname`) -1. Quickly edit/reload profile (`esource`/`resource`) -2. `dockertags` list all tags for a given docker image -3. `ramdisk` (only on OSX) create a RAM disk. Default size: 1GB - ` ramdisk 4` -creates a 4GB RAM disk -4. `color` to print colored text (see 3. in the Misc section): - color $Red "This will be printed in red" - color $Yellow "This will be printed in red" -5. `mecp` to copy files back to the machine from wich you are ssh-ing. - For this to work an ssh tunnel with Remoteforward is needed: - ssh -R 22:localhost:2222 YOURHOSTNAMEHERE - or specify this in ~/.ssh/config: - Host YOURHOSTNAMEHERE - Remoteforward 2222 localhost:22 - This can be enabled in ~/.ssh/config globally for all hosts by uncommenting the relevant `Host * Remoteforward`. - You might have to manually edit the username in the mecp definition in functions.sh if this is - different between the two machines. mecp copies by default on the local machine on ~/Desktop/ -5. Many more. Type "list_functions" to list defined functions and a small description + color $Red "This will be printed in red" + color $Yellow "This will be printed in red" +4. `mecp` to copy files back to the machine from wich you are ssh-ing. + For this to work an ssh tunnel with `Remoteforward` is needed: + + ssh -R 22:localhost:2222 YOURHOSTNAMEHERE + + or specify this in `~/.ssh/config` for a persistent configuration: + + Host YOURHOSTNAMEHERE + Remoteforward 2222 localhost:22 + + This can be enabled in `~/.ssh/config` globally for all hosts by uncommenting the relevant `Host * Remoteforward`. + You might have to manually edit the username in the `mecp` definition in `functions.sh` if this is + different between the two machines. `mecp` copies by default on the local machine on `~/Desktop/` + +5. Many more. Use `list_functions` to list defined functions and a small description + +### Files/Folders -### Files/Folders ### 1. `~/bin`, `~/git`, `~/projects` folders 2. ssh config (`~/.ssh/config`): - * Create ssh keys if not defined already - * Keep connections alive by increasing timeout time - * Include multiplexer to allow quick multiple connections to the same host - * (Optional: Compression, this should allow more responsive shells with slow connections, -but will slow things down when copying large files. My suggestion is to have compression enabled -on a by-host basis in `~/.ssh/config`) -3. brethil.zsh-theme, brethil-minimal.zsh-themes, themes for oh-my-zsh, symlinked in `$ZSH/custom/themes` ($ZSH=~/.oh-my-zsh) -4. ~/.dotfiles_functions, ~/.dotfiles_aliases are sourced by this dotfiles, allowing for custom functions/aliases + - Create ssh keys if not defined already + - Keep connections alive by increasing timeout time + - Include multiplexer to allow quick multiple connections to the same host + - (Optional: Compression, this should allow more responsive shells with slow connections, + but will slow things down when copying large files. My suggestion is to have compression enabled + on a by-host basis in `~/.ssh/config`) +3. `brethil.zsh-theme`, `brethil-minimal.zsh-themes`, themes for oh-my-zsh, + symlinked in `$ZSH/custom/themes` (`$ZSH=~/.oh-my-zsh`) +4. `~/.dotfiles_functions`, `~/.dotfiles_aliases` are sourced by this dotfiles, allowing for custom functions/aliases 5. useful_commands contains a list of useful commands (the first rule of the tautology club...) -### Misc ### +### Misc -1. Colored output (via `grc`) for several commands. -2. Easy names for ANSI color escapes (Black, Red, Green, Yellow, Blue, Cyan, Purple, White, CLEAR), -for example: +1. Colored output (via `grc`) for several commands. +2. Easy names for ANSI color escapes (Black, Red, Green, Yellow, Blue, Cyan, Purple, White, CLEAR), for example: - `echo -e "${Green}This text will be green${CLEAR}"` + echo -e "${Green}This text will be green${CLEAR}" -will result in green text. Use `$CLEAR` to clear previous escape sequences add B before the variable (check colors.sh) -name to use **bold** and U to underline (examples: $BRed, $UBlack for bold red and underlined black) -3. Type `esc` twice to add `sudo` before the current command (oh-my-zsh's `sudo` plugin) -4. Autoupdate script running every two weeks, autoupdate function: dotfiles_selfupdate (or `git pull` from `$DOTFILES` folder) -5. Automatic fix of the `SSH_AUTH_SOCK` enviroment variable: `~/.ssh/rc` is installed run on every ssh login, -and updates a symlink pointing (`~/.ssh/ssh_auth_sock`). `SSH_AUTH_SOCK` points to this (set in `brethil_dotfile.sh`). -The idea is that if the user is logging in using ssh -A, and using tmux, it will be possible to use -the remote socket over different sessions by always using the symlink. + will result in green text. Use `$CLEAR` to clear previous escape sequences add B before the variable (check `colors.sh`) + name to use **bold** and U to underline (examples: `$BRed`, `$UBlack` for bold red and underlined black) + +3. Autoupdate script running every two weeks, autoupdate function: `dotfiles_selfupdate` (or `git pull` from `$DOTFILES`folder) +4. Automatic fix of the`SSH_AUTH_SOCK`environment variable:`~/.ssh/rc` is installed run on every ssh login, + and updates a symlink pointing (`~/.ssh/ssh_auth_sock`). `SSH_AUTH_SOCK`points to this (set in`brethil_dotfile.sh`). + The idea is that if the user is logging in using `ssh -A`, and using tmux, it will be possible to use + the remote socket over different sessions by always using the symlink.