I just released Wok 0.3.0, whose main addition per se is worktree support. Nevertheless, I realized I never introduced the project properly. Time to do it.

Introducing: Wok

Wok is a CLI application that helps managing coding projects on the local laptop. It's an opinionated set of smart scripts that basically help me moving around project folders without thinking and typing too much. It does so by using some conventions and leveraging shell's autocomplete features.

The name wok is at the same time: a reference to the word workspace, an homage to my lovely wife, a pun on my sloppy R (which for a Romanesco native speaker is a big thing, trust me), a very short word to type.

The CLI design

The core principles are: type less, learn incrementally, build muscle memory. Navigating project should feel like using keybinding in the IDE.

With that in mind, I designed the wok command to be smart enough to understand what to do for the most repetitive actions (cloning projects, cd-ing into projects) and to use flags to enforce some less-used action (like list projects and import/export workspaces).

Another key point is that invoking wok should have the same effect regardless of the current working directory; that is, running wok balanza/example will always move the shell to the example project root directory.

Some examples

To add a project, you can clone it with

> wok git@github.com:balanza/awesomeproject.git

Wok receives a URL and then understand it has to clone. git is used underlying, so whatever authentication method is needed is inherited by the git configuration.

Regardless of where the command is executed, the project is cloned into ~/Workspace/balanza/awesomeproject (the default workspace directory can be set with the WOK_SPACE environment variable).

Then every time you need to move into the project's root folder, just

> wok balanaza/awesomeproject

or use the autocomplete with <TAB>

> wok balawesom<TAB>
balanza/awesomeproject balanza/someotherproject

How to start with Wok

First get the application using the installation script:

> curl -sSL https://raw.githubusercontent.com/balanza/wok/main/install.sh | bash

Wok is tightly bound with the running shell to provide the most seamless integration possible. It requires some setup before the first usage, just run wok and the needed operations will be detected automatically.

> wok
╭─────────────────────────────────────╮
│             WOK v0.3.0              │
╰─────────────────────────────────────╯

  Using default workspace '/home/emanuele/Workspace'

  37 projects in 13 organizations

Setup Status:
  ✗ Wokrc File - Todo
  ✓ Wokrc Configuration - Done
  ✗ Autocomplete File - Todo

⚠ Wok needs to be setup to work correctly.
Do you want to update the setup now? (y/n):

Type y and you are done, you can start adding project to your workspace. Now, if you list the projects with

> wok -l

You will probably see an empty list. This is because Wok relies on a specific folder structure to read projects. As you probably didn't already organize your file system as Wok expects, you will need to move your current projects

> wok --scrape .
✔ Found 2 repositories
  balanza/oldproject
  torvalds/linux
Options:
  1. Import repositories into current workspace
  2. Save to JSON file (can be imported later)
  3. Abort

Enter your choice [1-3]:

will recursively scan the provided directory searching for git repository, so that you can move them into your new workspace.

Final words

I wrote Wok for my needs and it's tailored around what I do. My work setup is Linux with ZSH, (almost) all the projects I contribute to use .git as svc and Github for hosting, I use both neovim and vscode as IDE. Nevertheless, I'm trying to build features that can sound to other developers, too.

If you find it interesting for you, reach out in the repository: https://github.com/balanza/wok.