more markdown

README.md

@@ -2,7 +2,6 @@
 
 # fw
 
-[<file:https://github.com/brocode/fw/actions/workflows/rust.yml/badge.svg?branch=master>](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)

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!

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 <NAME>` 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 [email protected]: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 [email protected]: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
+\<enter\> 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.