From b9af2b78c5f4a6a193b51757a3acffde06e9035a Mon Sep 17 00:00:00 2001 From: Patrick Haun Date: Tue, 21 Nov 2023 11:38:27 +0100 Subject: [PATCH] more markdown --- README.md | 1 - doc/installation.md | 144 +++++++++++++++++++++++++++++++++++++++++++ doc/installation.org | 113 --------------------------------- doc/usage.md | 106 +++++++++++++++++++++++++++++++ doc/usage.org | 94 ---------------------------- 5 files changed, 250 insertions(+), 208 deletions(-) create mode 100644 doc/installation.md delete mode 100644 doc/installation.org create mode 100644 doc/usage.md delete mode 100644 doc/usage.org diff --git a/README.md b/README.md index db0d5b06..835e9593 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,6 @@ # fw -[](https://github.com/brocode/fw/blob/nested-values/.github/workflows/rust.yml) [![](https://img.shields.io/crates/v/fw.svg)](https://crates.io/crates/fw) [![](https://asciinema.org/a/222856.png)](https://asciinema.org/a/222856) diff --git a/doc/installation.md b/doc/installation.md new file mode 100644 index 00000000..ed6bdcaf --- /dev/null +++ b/doc/installation.md @@ -0,0 +1,144 @@ +# Installation + +The best way to install fw is the rust tool cargo. + +``` bash +cargo install fw +``` + +If you are using OSX, [rustup](https://rustup.rs/) is recommended but +you [should be able to use brew +too](https://github.com/Homebrew/homebrew-core/pull/14490). + +If you\'re lucky enough to be an arch linux user: +[AUR](https://aur.archlinux.org/packages/fw/) + +If you are running on Windows then you will have some issue compiling +openssl. Please refer to compiling with rust-openssl +[here](https://github.com/sfackler/rust-openssl/blob/5948898e54882c0bedd12d87569eb4dbee5bbca7/README.md#windows-msvc) + +## With fzf + +Since we integrate with [fzf](https://github.com/junegunn/fzf) it is +recommended to use that or [skim](https://github.com/lotabout/skim) for +the best possible experience (`workon` and `nworkon` will be helm-style +fuzzy finders). Make sure `fzf` is installed and then add this to your +shell configuration: + +Zsh (This shell is used by the project maintainers. The support for +other shells is untested by us): + +``` shell-script +if [[ -x "$(command -v fw)" ]]; then + if [[ -x "$(command -v fzf)" ]]; then + eval $(fw print-zsh-setup -f 2>/dev/null); + else + eval $(fw print-zsh-setup 2>/dev/null); + fi; +fi; +``` + +Bash: + +``` shell-script +if [[ -x "$(command -v fw)" ]]; then + if [[ -x "$(command -v fzf)" ]]; then + eval "$(fw print-bash-setup -f 2>/dev/null)" + else + eval "$(fw print-bash-setup 2>/dev/null)" + fi +fi +``` + +Fish: + +``` shell-script +if test -x (command -v fw) + if test -x (command -v fzf) + fw print-fish-setup -f | source + else + fw print-fish-setup | source + end +end +``` + +## With skim + +We also integrate with [skim](https://github.com/lotabout/skim), you can +use that instead of fzf for the best possible experience (`workon` and +`nworkon` will be helm-style fuzzy finders). + +If you have cargo installed you can install skim like this: + +``` shell-script +cargo install skim +``` + +Make sure `skim` is installed and then add this to your shell +configuration: + +Zsh (This shell is used by the project maintainers. The support for +other shells is untested by us): + +``` shell-script +if [[ -x "$(command -v fw)" ]]; then + if [[ -x "$(command -v sk)" ]]; then + eval $(fw print-zsh-setup -s 2>/dev/null); + else + eval $(fw print-zsh-setup 2>/dev/null); + fi; +fi; +``` + +Bash: + +``` shell-script +if [[ -x "$(command -v fw)" ]]; then + if [[ -x "$(command -v sk)" ]]; then + eval "$(fw print-bash-setup -s 2>/dev/null)" + else + eval "$(fw print-bash-setup 2>/dev/null)" + fi +fi +``` + +Fish: + +``` shell-script +if test -x (command -v fw) + if test -x (command -v sk) + fw print-fish-setup -s | source + else + fw print-fish-setup | source + end +end +``` + +## Without fzf or skim + +If you don\'t want `fzf` or `skim` integration: + +Zsh (This shell is used by the project maintainers. The support for +other shells is untested by us): + +``` shell-script +if [[ -x "$(command -v fw)" ]]; then + eval $(fw print-zsh-setup 2>/dev/null); +fi; +``` + +Bash: + +``` shell-script +[[ -x "$(command -v fw)" ]] && eval "$(fw print-bash-setup)" +``` + +Fish: + +``` shell-script +test -x (command -v fw) && fw print-fish-setup | source +``` + +In this case, `workon` and `nworkon` will require an argument (the +project) and will provide simple prefix-based autocompletion. You should +really use the `fzf` or `skim` integration though, it\'s much better! diff --git a/doc/installation.org b/doc/installation.org deleted file mode 100644 index 66577311..00000000 --- a/doc/installation.org +++ /dev/null @@ -1,113 +0,0 @@ -* Installation - The best way to install fw is the rust tool cargo. - #+BEGIN_SRC bash - cargo install fw - #+END_SRC - - If you are using OSX, [[https://rustup.rs/][rustup]] is recommended but you [[https://github.com/Homebrew/homebrew-core/pull/14490][should be able to use brew too]]. - - If you're lucky enough to be an arch linux user: [[https://aur.archlinux.org/packages/fw/][AUR]] - - If you are running on Windows then you will have some issue compiling openssl. Please refer to compiling with rust-openssl [[https://github.com/sfackler/rust-openssl/blob/5948898e54882c0bedd12d87569eb4dbee5bbca7/README.md#windows-msvc][here]] - -** With fzf - Since we integrate with [[https://github.com/junegunn/fzf][fzf]] it is recommended to use that or [[https://github.com/lotabout/skim][skim]] for the best possible experience (~workon~ and ~nworkon~ will be helm-style fuzzy finders). - Make sure ~fzf~ is installed and then add this to your shell configuration: - - Zsh (This shell is used by the project maintainers. The support for other shells is untested by us): - #+BEGIN_SRC shell-script - if [[ -x "$(command -v fw)" ]]; then - if [[ -x "$(command -v fzf)" ]]; then - eval $(fw print-zsh-setup -f 2>/dev/null); - else - eval $(fw print-zsh-setup 2>/dev/null); - fi; - fi; - #+END_SRC - - Bash: - #+BEGIN_SRC shell-script - if [[ -x "$(command -v fw)" ]]; then - if [[ -x "$(command -v fzf)" ]]; then - eval "$(fw print-bash-setup -f 2>/dev/null)" - else - eval "$(fw print-bash-setup 2>/dev/null)" - fi - fi - #+END_SRC - - Fish: - #+BEGIN_SRC shell-script - if test -x (command -v fw) - if test -x (command -v fzf) - fw print-fish-setup -f | source - else - fw print-fish-setup | source - end - end - #+END_SRC - -** With skim - We also integrate with [[https://github.com/lotabout/skim][skim]], you can use that instead of fzf for the best possible experience (~workon~ and ~nworkon~ will be helm-style fuzzy finders). - - If you have cargo installed you can install skim like this: - #+BEGIN_SRC shell-script - cargo install skim - #+END_SRC - Make sure ~skim~ is installed and then add this to your shell configuration: - - Zsh (This shell is used by the project maintainers. The support for other shells is untested by us): - #+BEGIN_SRC shell-script - if [[ -x "$(command -v fw)" ]]; then - if [[ -x "$(command -v sk)" ]]; then - eval $(fw print-zsh-setup -s 2>/dev/null); - else - eval $(fw print-zsh-setup 2>/dev/null); - fi; - fi; - #+END_SRC - - Bash: - #+BEGIN_SRC shell-script - if [[ -x "$(command -v fw)" ]]; then - if [[ -x "$(command -v sk)" ]]; then - eval "$(fw print-bash-setup -s 2>/dev/null)" - else - eval "$(fw print-bash-setup 2>/dev/null)" - fi - fi - #+END_SRC - - Fish: - #+BEGIN_SRC shell-script - if test -x (command -v fw) - if test -x (command -v sk) - fw print-fish-setup -s | source - else - fw print-fish-setup | source - end - end - #+END_SRC - -** Without fzf or skim - If you don't want ~fzf~ or ~skim~ integration: - - Zsh (This shell is used by the project maintainers. The support for other shells is untested by us): - #+BEGIN_SRC shell-script - if [[ -x "$(command -v fw)" ]]; then - eval $(fw print-zsh-setup 2>/dev/null); - fi; - #+END_SRC - - Bash: - #+BEGIN_SRC shell-script - [[ -x "$(command -v fw)" ]] && eval "$(fw print-bash-setup)" - #+END_SRC - - Fish: - #+BEGIN_SRC shell-script - test -x (command -v fw) && fw print-fish-setup | source - #+END_SRC - - In this case, ~workon~ and ~nworkon~ will require an argument (the project) and will provide simple prefix-based autocompletion. - You should really use the ~fzf~ or ~skim~ integration though, it's much better! diff --git a/doc/usage.md b/doc/usage.md new file mode 100644 index 00000000..62e8d8dc --- /dev/null +++ b/doc/usage.md @@ -0,0 +1,106 @@ +# Usage + +### Overriding the config file location / multiple config files (profiles) + +Just set the environment variable `FW_CONFIG_DIR`. This is also honored +by `fw setup` and `fw org-import` so you can create more than one +configuration this way and switch at will. + +### Migrating to `fw` / Configuration + +Initial setup is done with + +``` bash +fw setup DIR +``` + +This will look through `DIR` (flat structure!) and inspect all git +repositories, then write the configuration in your home. You can edit +the configuration manually to add stuff. If you have repositories +elsewhere you will need to add them manually and set the `override_path` +property. The configuration is portable as long as you change the +`workspace` attribute, so you can share the file with your colleagues +(projects with `override_path` set won\'t be portable obviously. You can +also add shell code to the `after_clone` and `after_workon` fields on a +per-project basis. `after_clone` will be executed after cloning the +project (interpreter is `sh`) and `after_workon` will be executed each +time you `workon` into the project. + +If you want to pull in all projects from a GitHub organization there\'s +`fw org-import ` for that (note that you need a minimal config +first). + +### Turn `fw` configuration into reality + +From now on you can + +``` bash +fw sync # Make sure your ssh agent has your key otherwise this command will just hang because it waits for your password (you can't enter it!). +``` + +which will clone all missing projects that are described by the +configuration but not present in your workspace. Existing projects will +be synced with the remote. That means a fast-forward is executed if +possible. + +### Running command across all projects + +There is also + +``` bash +fw foreach 'git remote update --prune' +``` + +which will run the command in all your projects using `sh`. + +### Updating `fw` configuration (adding new project) + +Instead of cloning new projects you want to work on, I suggest adding a +new project to your configuration. This can be done using the tool with + +``` bash +fw add git@github.com:brocode/fw.git +``` + +(you should run `fw` sync afterwards! If you don\'t want to sync +everything use `fw sync -n`) In case you don\'t like the computed +project name (the above case would be `fw`) you can override this (like +with `git clone` semantics): + +``` bash +fw add git@github.com:brocode/fw.git my-fw-clone +``` + +If you\'re an emacs user you should always run + +``` bash +fw projectile +``` + +after a `sync`. This will overwrite your projectile bookmarks so that +all your `fw` managed projects are known. Be careful: Anything that is +not managed by fw will be lost. + +## workon usage + +Just + +``` bash +workon +``` + +It will open a fuzzy finder which you can use to select a project. Press +\ on a selection and it will drop you into the project folder +and execute all the hooks. + +If you\'re in a pinch and just want to check something real quick, then +you can use + + nworkon + +as that will no execute any post-workon hooks and simply drop you into +the project folder. + +In case you\'re not using `fzf` integration (see above) you will need to +pass an argument to `workon` / `nworkon` (the project name). It comes +with simple prefix-based autocompletion. diff --git a/doc/usage.org b/doc/usage.org deleted file mode 100644 index d44b3919..00000000 --- a/doc/usage.org +++ /dev/null @@ -1,94 +0,0 @@ -* Usage -*** Overriding the config file location / multiple config files (profiles) - Just set the environment variable ~FW_CONFIG_DIR~. This is also - honored by ~fw setup~ and ~fw org-import~ so you can create more than - one configuration this way and switch at will. -*** Migrating to ~fw~ / Configuration - Initial setup is done with - - #+BEGIN_SRC bash - fw setup DIR - #+END_SRC - - This will look through ~DIR~ (flat structure!) and inspect all git - repositories, then write the configuration in your home. You can - edit the configuration manually to add stuff. If you have - repositories elsewhere you will need to add them manually and set - the ~override_path~ property. The configuration is portable as long - as you change the ~workspace~ attribute, so you can share the file - with your colleagues (projects with ~override_path~ set won't be - portable obviously. You can also add shell code to the ~after_clone~ - and ~after_workon~ fields on a per-project basis. ~after_clone~ will be - executed after cloning the project (interpreter is ~sh~) and - ~after_workon~ will be executed each time you ~workon~ into the project. - - If you want to pull in all projects from a GitHub organization - there's ~fw org-import ~ for that (note that you need a minimal - config first). - -*** Turn ~fw~ configuration into reality - From now on you can - - #+BEGIN_SRC bash - fw sync # Make sure your ssh agent has your key otherwise this command will just hang because it waits for your password (you can't enter it!). - #+END_SRC - - which will clone all missing projects that are described by the - configuration but not present in your workspace. Existing projects - will be synced with the remote. That means a fast-forward is - executed if possible. - -*** Running command across all projects - There is also - #+BEGIN_SRC bash - fw foreach 'git remote update --prune' - #+END_SRC - which will run the command in all your projects using ~sh~. - -*** Updating ~fw~ configuration (adding new project) - Instead of cloning new projects you want to work on, I suggest - adding a new project to your configuration. This can be done using - the tool with - - #+BEGIN_SRC bash - fw add git@github.com:brocode/fw.git - #+END_SRC - - (you should run ~fw~ sync afterwards! If you don't want to sync - everything use ~fw sync -n~) In case you don't like the computed - project name (the above case would be ~fw~) you can override this - (like with ~git clone~ semantics): - - #+BEGIN_SRC bash - fw add git@github.com:brocode/fw.git my-fw-clone - #+END_SRC - - If you're an emacs user you should always run - #+BEGIN_SRC bash - fw projectile - #+END_SRC - - after a ~sync~. This will overwrite your projectile bookmarks so that - all your ~fw~ managed projects are known. Be careful: Anything that is - not managed by fw will be lost. - - -** workon usage - Just - - #+BEGIN_SRC bash - workon - #+END_SRC - - It will open a fuzzy finder which you can use to select a project. - Press on a selection and it will drop you into the project folder and execute all the hooks. - - If you're in a pinch and just want to check something real quick, then you can use - - #+BEGIN_SRC - nworkon - #+END_SRC - as that will no execute any post-workon hooks and simply drop you into the project folder. - - In case you're not using ~fzf~ integration (see above) you will need to pass an argument to ~workon~ / ~nworkon~ (the project name). - It comes with simple prefix-based autocompletion.