Fw: Workspace Productivity Booster in Rust

Why fw?

With fw you have a configuration 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.

The default configuration location is located under your system’s config directory as described here. That is :

Linux: ~/.config/fw
MacOS: $HOME/Library/Application Support/fw
Windows: {FOLDERID_RoamingAppData}\fw

The location and can be overridden by setting FW_CONFIG_DIR.

Per default projects are cloned into ${settings.workspace}/${project.name} but you can override that by setting an override_path attribute as seen in the example configuration.

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-agent based 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)

Discord

In the case you want to talk about new features or give us direct feedback, you can join the Discord (Thanks @rawkode) in the channel #fw.

The best way to install fw is the rust tool cargo.

cargo install fw

If you are using OSX, rustup is recommended but you should be able to use brew too.

If you’re lucky enough to be an arch linux user: AUR

If you are running on Windows then you will have some issue compiling openssl. Please refer to compiling with rust-openssl here

With fzf

Since we integrate with fzf it is recommended to use that or 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):

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:

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:

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, 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:

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):

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:

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:

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):

if [[ -x "$(command -v fw)" ]]; then
  eval $(fw print-zsh-setup 2>/dev/null);
fi;

Bash:

[[ -x "$(command -v fw)" ]] && eval “$(fw print-bash-setup)”

Fish:

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!

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

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

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

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

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):

fw add git@github.com:brocode/fw.git my-fw-clone

If you’re an emacs user you should always run

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

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.