11 releases (5 breaking)
0.6.0 | Aug 8, 2024 |
---|---|
0.5.1 | Jul 19, 2024 |
0.5.0 | Apr 8, 2024 |
0.4.2 | Jan 2, 2024 |
0.1.1 | Oct 31, 2023 |
#199 in Filesystem
47 downloads per month
68KB
1.5K
SLoC
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
Program | Purpose | Required |
---|---|---|
fzf |
Selecting Projects | Yes |
gh |
Viewing and Cloning github projects | Optional |
git |
Checking the status of local repos | Optional |
tmux |
Terminal Multliplexer that projects are launched in | Yes |
tmuxinator |
Session manager for tmux |
Yes |
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
Option | Purpose | Default Value |
---|---|---|
projects_dir |
Where workflows should look for projects. Paths are relative to $HOME |
["Projects/]" |
open_new_projects |
Whether projects should be opened after they have been created with --create |
true |
fzf configuration
Option | Purpose | Default Value |
---|---|---|
layout |
The layout fzf should use, either default , reverse , or reverse-list |
"default" |
border |
The border fzf should display around the finder. Options include: rounded , sharp , none , etc. For more run fzf --help . All fzf border types are supported. |
"none" |
border_label |
The label to show in the border. If blank or no border is selected, the label won't show | "" |
open_prompt |
The prompt fzf should show when opening a project | "Open: " |
delete_prompt |
The prompt fzf should show when deleteing a project | "Delete: " |
pointer |
The pointer to the current item in fzf | ">" |
theme |
The theme to use with fzf. Options include: dark , light , 16 , bw |
"dark" |
template_prompt | The default prompt for selecting a template | "Select a template: " |
no_template_option | What the option for selecting no template is called | "No Template" |
github configuration
NOTE Both of these options require the gh
cli tool, and for the user to be logged in.
Option | Purpose | Default Value |
---|---|---|
enabled |
Whether to enable GitHub Intergration | true |
confirm_cloning |
Whether to ask for confirmation before cloning a git repo into ~/Projects/ |
true |
project_indicator |
A string that is prepended to a github project in the list view, to disable leave blank. | |
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.
Option | Purpose | Default Value |
---|---|---|
check_tree |
Check if the git repo has a clean working tree before deletion | true |
check_push |
Check if the git repo has been pushed before deletion | true |
tmuxinator configuration
Option | Purpose | Default Value |
---|---|---|
fresh_config |
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 | false |
window_names |
An array of names of the tmux windows tmuxinator should create | ["editor"] |
start_commands |
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. | ["nvim ."] |
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
Dependencies
~4–13MB
~169K SLoC