Workflows

A CLI tool for creating a seamless workflow with remote and local git repos.

workflows allows users to view projects on their GitHub and their local machine. The selected project is then opened in a tmux session.

If the selected project is not already present on the user's machine, it is cloned from GitHub and then opened in a tmux session.

Projects are selected using fzf for a fluent keyboard driven workflow.

Requirements

workflows makes use of the following programs

Both gh and git integration can be disabled via configuration, however they are both enabled by default.

Checking Requirements

To check if the needed programs are installed, run workflows health check

workflows --health

Installation

Installing from cargo

cargo install workflows

Installing latest from source

cargo install --git https://github.com/danielronalds/workflows

Building from source

git clone https://github.com/danielronalds/workflows
cd workflows
cargo build --release

Usage

Opening a project

To open a project, open a terminal and run workflows. You'll be greeted with a fzf UI with your list of projects. Local projects will be displayed instantly, however GitHub projects may take a second to load in depending on your connection strength. Select the project you'd like to open, and it'll be launched in a tmux session. If a tmuxinator config doesn't exist for the project, one will be created.

Projects are stored in ~/Projects/ by default, however this can be changed via the configuration file. This is also where GitHub projects are cloned to. If a project exists elsewhere on your system it won't be detected.

What commands are run with tmuxinator can be configured using the config file.

--open shortcut

If you're visiting a particular project frequently, it might be helpful to have the shortcut in your recent terminal history. This isn't possible through the fzf interface, which is where the --open (or -o) command comes in.

You can open a local project directly by supplying the projects name in full as an argument to the --open command:

workflows --open workflows

The following also works:

workflows -o workflows

Creating a project

To create a project, run workflows --new <project-name>. This creates a directory with the name of the project in the projects directory. A tmuxinator config is created and run, launching the project in tmux.

The command --new can be exchanged for the shorthand -n.

Templates

When creating a project, you'll often want to use some kind of CLI generation tool, e.g. cargo init. Using templates, this can be done when a project is created.

Templates define a series of commands to be run upon a project's creation using the --new command. For example, if you wanted a template that scaffolded a cargo binary project, the template in your config file would look like the following:

[[template]]
name="Rust Binary"
commands=["cargo init --bin"]

Using the project name

When templates are run, the projects name is stored in an environment variable, WORKFLOWS_PROJECT_NAME. This can be used for templates that require knowledge of the projects name to scaffold it, such as creating a Go project:

[[template]]
name="Go Project"
commands=[
  "go mod init github.com/danielronalds/$WORKFLOWS_PROJECT_NAME",
  "git init",
  "git branch -m main"
]

Deleting a project

To delete a project, run workflows --delete. You'll be greeted with a fzf UI, but only with local projects. Selecting one will cause checks to be run on whether the repo has a clean working tree and is pushed to main. NOTE this only works for remote branches. With confirmation the project will be deleted.

Deleting using workflows --delete deletes the tmuxinator config as well as the project in the projects directory.

Deleting a known project

If you know the exact name of the project you're wanting to delete, you can also use workflows --delete <PROJECT_NAME>.

For example, if you wanted to delete a project called test-proj, you could run workflows --delete test-proj. This bypasses fzf.

Cloning a project

Workflows can also be used to clone git repos using workflows --clone, or the short flag -c. This command is helpful for checking out projects that are not your own, and thus do not show up in the default open prompt.

Configuration

workflows is configured by a toml file in either of the following paths

• ~/.config/workflows/config.toml
• ~/.workflows.toml

If the first option cannot be found, the second one is looked for. If neither is present then the default configuration is used

Default Configuration

[general]
projects_dirs=["Projects/"]
open_new_projects=true

[fzf]
layout="default"
border="none"
border_label=""
open_prompt="Open: "
delete_prompt="Delete: "
pointer=">"
theme="dark"
template_prompt="Select a template: "
no_template_option="No Template"

[github]
enabled=true
confirm_cloning=true
project_indicator="  "

[git]
check_tree=true
check_push=true

[tmuxinator]
fresh_config=false
window_names=["editor"]
start_commands=["nvim ."]

General configuration

fzf configuration

github configuration

NOTE Both of these options require the gh cli tool, and for the user to be logged in.

git configuration

NOTE Both of these options require git, and for the project to be a git repo. If one of these requirements is not fulfilled then both of these options will always be false when run.

tmuxinator configuration

Window Manager Integration

I wrote this program to be used with a window manager in mind, as it encourages even less interaction with a mouse. It has only been tested on Hyprland using kitty.

Hyprland Keybinds

This snippet below adds a bind for launching workflows with kitty in Hyprland

bind=SUPER_SHIFT,W,exec,kitty workflows

And this one is for running delete mode

bind=SUPER_SHIFT_CTRL,W,exec,kitty workflows --delete