8 unstable releases (3 breaking)
|Jan 2, 2024
|Dec 25, 2023
|Nov 13, 2023
|Nov 10, 2023
|Oct 31, 2023
#496 in Command line utilities
200 downloads per month
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.
workflows makes use of the following programs
|Viewing and Cloning github projects
|Checking the status of local repos
|Terminal Multliplexer that projects are launched in
|Session manager for
git integration can be disabled via configuration,
however they are both enabled by default.
To check if the needed programs are installed, run workflows health check
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
cargo build --release
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
What commands are run with
tmuxinator can be configured using
the config file.
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
--new can be exchanged for the shorthand
Deleting a project
To delete a project, run
workflows --delete. You'll be greeted
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.
workflows --delete deletes the tmuxinator config
as well as the project in the projects directory.
Cloning a project
Workflows can also be used to clone git repos using
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.
workflows is configured by a toml file in either of the following paths
If the first option cannot be found, the second one is looked for. If neither is present then the default configuration is used
workflows should look for projects. Path is relative to $HOME
|The layout fzf should use, either
|The border fzf should display around the finder. Options include:
none, etc. For more run
fzf --help. All fzf border types are supported.
|The label to show in the border. If blank or no border is selected, the label won't show
|The prompt fzf should show when opening a project
|The prompt fzf should show when deleteing a project
|The pointer to the current item in fzf
|The theme to use with fzf. Options include:
NOTE Both of these options require the
gh cli tool, and for the user to be logged in.
|Whether to enable GitHub Intergration
|Whether to ask for confirmation before cloning a git repo into
|A string that is prepended to a github project in the list view, to disable leave blank.
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.
|Check if the git repo has a clean working tree before deletion
|Check if the git repo has been pushed before deletion
|If enabled, a tmuxinator configuration will be generated before every project launch. This can be useful if you've updated the other two options below
|An array of names of the tmux windows tmuxinator should create
|An array of the commands to run for each window when tmux is started. If there are not enough commands for the defined windows, then the default option is used.
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.
This snippet below adds a bind for launching
workflows with kitty in Hyprland
And this one is for running delete mode
bind=SUPER_SHIFT_CTRL,W,exec,kitty workflows --delete