- fw [[https://travis-ci.org/brocode/fw][file:https://travis-ci.org/brocode/fw.svg?branch=master]] [[https://crates.io/crates/fw][file:https://img.shields.io/crates/v/fw.svg]]
** Why fw?
With fw you have a JSON file describing your workspace.
It takes care of cloning projects and can run commands across your entire workspace.
You can start working on any project quickly, even if it's not in your flat structured workspace (better than CDPATH!).
It also "sets up" your environment when you start working on a project (compile stuff, run make, activate virtualenv or nvm, fire up sbt shell, etc.)
Here's an example configuration that should be easy to grasp:
#+BEGIN_SRC javascript
{
"projects": {
"pybuilder": {
"name": "pybuilder",
"git": "git@github.com:pybuilder/pybuilder.git",
"after_clone": "virtualenv venv && source venv/bin/activate && ./build.py install_dependencies",
"after_workon": "source venv/bin/activate"
},
"fw": {
"name": "fw",
"git": "git@github.com:brocode/fw.git",
"after_clone": "cargo build",
"tags": ["git", "rust", "brocode"]
},
"docker": {
"name": "docker",
"git": "git@github.com:docker/docker.git",
"override_path": "/home/brocode/go/src/github.com/docker/docker"
}
},
"settings": {
"workspace": "~/workspace",
"tags": {
"git": {
"after_workon": "git remote update --prune",
"priority": 0 // lowest priority tags run first
},
"js": {
"after_workon": "source /.nvm/nvm.sh"
},
"rust": {
"after_clone": "cargo build",
"after_workon": "cargo test && rustup run nightly cargo clippy"
},
"brocode": {
"priority": 100, // highest priority tag wins workspace resolution
"workspace": "/workspace/brocode/"
},
}
}
}
#+END_SRC
Per default projects are cloned into ${settings.workspace}/${project.name} but you can override that by setting an override_path attribute as seen above.
** What this is, and isn't
fw is a tool I wrote to do my bidding. It might not work for you if your workflow differs a lot from mine or might require adjustments.
Here are the assumptions:
- only git repositories
- only ssh clone (easily resolveable by putting more work in the git2 bindings usage)
ssh-agentbased authentication
*** If you can live with all of the above, you get:
- workspace persistence (I can rm -rf my entire workspace and have it back in a few minutes)
- ZERO overhead project switching with the workon function (need to activate nvm? Run sbt? Set LCD brightness to 100%? fw will do all that for you)
- zsh completions on the project names for workon
- generate projectile configuration for all your project (no need to projectile-add-known-project every time you clone some shit, it will just work)
** Installation #+BEGIN_SRC bash cargo install fw #+END_SRC
If you are using OSX make sure that you got the rust toolchain from [[https://rustup.rs/][rustup]] and not from homebrew.
If you're using the homebrew formula you will run into [[https://github.com/mriehl/fw/issues/11][issues]].
*** With fzf
Another thing that will make you much more productive is to use the zsh completions (if you're not using the zsh I guess
you would get a bigger productivity boost by switching to zsh first).
Since we integrate with [[https://github.com/junegunn/fzf][fzf]] it is recommended to use that 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 zsh configuration:
#+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
*** Without fzf
If you don't want fzf integration:
#+BEGIN_SRC shell-script if [[ -x "$(command -v fw)" ]]; then eval $(fw print-zsh-setup 2>/dev/null); fi; #+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 integration instead it's much better!
** Usage
*** 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 .fw.json in your home.
You can edit that file manually to add stuff. If you have repositories elsewhere you will need to add them manually and set the override_path property.
The fw.json file 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.
*** Turn fw configuration into reality
From now on you can
#+BEGIN_SRC bash fw sync #+END_SRC
which will clone all missing projects that are described by .fw.json but not present in your workspace.
*** 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 .fw.json. 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!)
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.
** 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.