fw treats a workspace as a config file you can rebuild from scratch

A workspace is a config file, not a directory you remember to keep

fw starts from an unusual premise: your workspace is something you describe, and the directory it lives in is disposable. With fw you have a configuration describing your workspace, and it takes care of cloning projects and can run commands across your entire workspace.

The stated benefit follows from that premise directly. The documentation claims workspace persistence, meaning the author can remove the entire workspace directory and have it back in a few minutes. That is only true because the list of projects, their URLs and their setup commands all live in a text file rather than in the state of a directory that cannot be committed.

The other half of the pitch is project switching. The workon function is described as zero overhead, and the examples given are the small chores that normally interrupt a change of context: activate nvm, run sbt, set the LCD brightness to 100 percent. In other words fw is not only a clone manager, it is an environment setup script that runs when you start working on a project, so compile steps, make targets, virtualenv activation and shell commands are part of the workspace definition.

There is a limit on the ambition, and it is stated plainly. The author says fw is a tool written to do their bidding, and that it might not work for you if your workflow differs a lot from theirs, or might require adjustments.

Three hard assumptions, listed by the author

A section titled what this is, and isn't sets out the assumptions, and the list is short enough to quote in full because it defines the tool's reach. Only git repositories. Only ssh clone, which the author notes could easily be resolved by putting more work into the git2 bindings. And ssh-agent based authentication.

Those three lines are the real scope of fw. There is no support for mercurial or subversion, no support for cloning over https with credentials in a URL, and no fallback when ssh-agent is not running. The author is not apologetic about this, and the framing is that if you can live with all of the above, you get the listed benefits.

What you get is listed as workspace persistence, zero overhead project switching with the workon function, zsh completions on the project names for workon, and generated projectile configuration for all your projects. That last one deserves a note, because it fixes a specific daily annoyance: no need to run projectile-add-known-project every time something is cloned, because fw will just work.

The stack behind the tool is ordinary Rust. The dependency list in the manifest includes git2 for the git work, the toml crate for the configuration, serde and serde_json, walkdir and rayon for walking the workspace, regex and rand, indicatif for progress output, reqwest with tokio for network calls, an openssl crate built with the vendored feature, and yansi for coloured terminal output configured to detect the environment.

Where the config lives, and how to move it

The configuration file lives under the system config directory as described by the dirs crate, and the documentation lists the three platform paths explicitly:

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

The path can be overridden by setting the FW_CONFIG_DIR environment variable, which matters for a few practical reasons: a dotfiles repository wants the config somewhere it can be committed, a container may not have a home directory in the expected place, and a machine with several identities may want one config per identity.

Projects are cloned into a path built from the settings, by default ${settings.workspace}/${project.name}, and that location can be overridden per project with an override_path attribute. So the config is where the workspace root is decided, and the project entries decide where each project lands inside it.

The documentation links an example configuration and says it should be easy to grasp, and the example is referenced with a target of doc/example_config inside the repository, alongside an installation guide at doc/installation.md and a usage guide at doc/usage.md. The repository also ships a man directory and a logo directory, and the manifest lists the tool as a command line utility in the cargo category, with keywords covering workspace, productivity, cli, automation and developer-tools, alongside repository topics including projectmanager, projects and git.

The tool is installed as a binary, and the docs cover the details

There is no install command in the repository root documentation. The README links out to a separate installation document at doc/installation.md and a usage document at doc/usage.md, and the project publishes a crate on crates.io under the name fw, with the crate badge pointing there and an asciinema recording linked as a demonstration.

That split between the root page and the doc directory is worth noting if you are evaluating the project from a browser. The root page gives you the reasoning and the assumptions, and the doc directory holds the operational detail, which is exactly the kind of arrangement that makes a small project pleasant to read and slightly harder to search.

The crate itself is small in terms of what it ships. The manifest includes only src, the LICENSE and the README, so the published package is the binary source and its licence rather than a tree of examples or templates, and the version in the manifest is 2.21.0, matching the newest release tag.

The licence is WTFPL, which the manifest records alongside a categories entry of command-line-utilities and an edition of 2024. For a personal productivity tool that is a pragmatic choice, but it is worth knowing that it is not one of the permissive licences most companies have a policy for, and that a company distribution or vendoring review may ask questions about it.

The workon function is the piece you will actually feel

Everything else in fw supports the switching moment. The workon function is the entry point, and the documentation describes the cost of using it as zero overhead, with zsh completions on the project names so the function can be tab-completed.

The point of a completion here is that the project names are known to fw, not to your shell history. fw knows the set of projects because the config file lists them, which means completion reflects the config rather than what you happened to type before. That is the same source of truth that lets the workspace be rebuilt from nothing.

The environment setup happens at the same moment. The documentation lists compile stuff, run make, activate virtualenv or nvm, and fire up an sbt shell as examples of what fw sets up when you start working on a project. The LCD brightness example is a joke, but the pattern is real: these are shell commands run in a project directory, and the configuration file is where they live.

This is the design decision that separates fw from a directory of shell aliases. A script can set up an environment for one project, but keeping that script next to the project it describes, in a file that lists every project and its commands, is what makes the workspace reproducible.

Recent tags, an active branch, and a design that may not fit you

The maintenance picture is straightforward. The last push was on 2026-10-01, so the project is being worked on. The release tags tell a slower story: v2.21.0 from 2025-05-27, v2.20.0 from 2025-01-07, and then v2.19.1 from 2023-11-30, with a gap of more than a year between the 2023 tag and the two 2025 tags. The tag for v2.19.1 is named after the release while the two newer ones are plain version tags, so the naming of releases changed along the way.

The honest assessment is that fw is a personal tool with a small audience, and the author says so. The three assumptions, especially ssh-only cloning and ssh-agent authentication, are not edge cases for most working developers but they are not universal either. A team that clones a mixture of ssh and https repositories will hit the boundary on the first day.

The dependency on a flat structured workspace is also a real constraint. The documentation mentions the workon function lets you start working on a project quickly even if it is not in your flat structured workspace, and compares that to being better than CDPATH, so the tool does handle projects outside the configured workspace, but the workspace itself is the organizing principle rather than an optional convenience.

Editorial conclusion

Adopt fw if your working life is a set of git repositories under one directory, you already use ssh-agent, and you want a single declarative file that can rebuild that workspace and run commands across it. Do not adopt it if you work with non-git repositories, need https clones, or rely on a GUI project manager with shared state, since fw keeps no database of anything beyond the config file you write. Before you commit to it, check three things: that your clone URLs are ssh and your key is loaded in ssh-agent, because those are stated as hard assumptions, that FW_CONFIG_DIR is set if you want the config outside the default system config directory, and that the ${settings.workspace} path in your config points at a directory the tool can write to.

Frequently asked questions

Official sources

1. brocode/fw on GitHub
2. Issues
3. License: WTFPL
4. README
5. Releases