fj.sh
is a minimalist command-line task manager and runner. It allows you to set up shell functions for running tasks scoped to a local directory, and run them easily by using the shortcut fj mytask
.
To install it, just clone the repository and add a symbolic link name fj
to src/fj.sh
:
git clone --depth 1 https://github.com/gutomotta/fj.sh.git ~/.fj.sh
ln -s ~/.fj.sh/src/fj.sh /usr/local/bin/fj
chmod u+x /usr/local/bin/fj
If you have ever added ~/bin/
to your PATH
, you can optionally change /usr/local/bin/fj
by ~/bin/fj
.
For now, the only way to update this is by pulling the latest version from GitHub:
cd ~/.fj.sh
git pull origin master
Simply remove the repo (and the symbolic link to the executable) from your machine:
rm -rf ~/.fj.sh /usr/local/bin/fj
To use it:
- In the root of some repo, create a
fj.sh
file. - Add functions to it to perform common development tasks you usually need to run from your shell. From now on, we'll call those functions "tasks".
- Run them by invoking
fj mytask
from the repo root.
Take a look at an example local fj.sh
file:
#!/bin/bash
up() (
docker compose up -d
)
down() (
docker compose down
)
# it also works with function arguments!
test() (
python -m unittest "$@"
)
In this example, you could run fj up
from your project root instead of docker compose up -d
. Moreover, you can pass arguments to your tasks (for instance, you can run fj test test/test_users.py
).
Try it yourself!
fj.sh
has some built-in "meta-tasks". Those are special tasks you can run to help you manage your repo's tasks. These are the meta-tasks available currently:
Meta-task | Description | Long form | Short form |
---|---|---|---|
List tasks | Lists all tasks available in your fj.sh file. |
fj --list |
fj -l |
Help | Shows usage message. | fj --help |
fj -h |
Version | Prints current version of the fj.sh executable |
fj --version |
fj -v |
A side-note: tasks and meta-tasks can only be run from a directory where there's a fj.sh
file available.
I was talking to @flaviokr, and we realized every project we build needs some command-line utilities to be run rather frequently during the development process. We tried different approaches to organize local tasks and define useful aliases shared that we could share with the rest of the team, but none felt quite right. We wanted a minimal tool that made it easy to define functions or scripts that were scoped by repository, so we decided to build one.
Maybe. We looked around a bit before starting to develop our own local task manager, but haven't found a tool that fully convinced us. But we're pretty sure somebody out there has built something like fj.sh
. We just figured it wouldn't be too challenging to build one just the way we wanted. Also, it seemed fun.
Not at all—this aims to be a much simpler project. Many developers, including us, have used GNU Make to set up local tasks, but that is harder than simply writing shell functions because the tool is not designed for that purpose.