workflows

Crates.ioworkflows
lib.rsworkflows
version0.7.0
sourcesrc
created_at2023-10-30 22:47:09.277509
updated_at2024-11-25 09:06:16.840549
descriptionA cli tool for creating a seemless workflow with remote and local git repos
homepage
repositoryhttps://github.com/danielronalds/workflows
max_upload_size
id1019154
size87,038
Daniel (danielronalds)

documentation

README

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 Optional

gh, git, and tmuxinator 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]
enabled=true
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
enabled Whether tmuxinator should be used to launch projects. Tmuxinator supports setting up workspaces, however it also increases loadtime of a workspace. Disabling it results in projects being launched with a named session with a single window in the root of the project true
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
Commit count: 151

cargo fmt