gitflow

README

Gitflow [wip]

Gitflow is a CLI to help you manage multiple git repositories and implement git workflow.

Gitflow supports terminal auto completion (triggered by tab), and fuzzy searching based on fzf, to help you operate git repositories more efficiently.

Also, gitflow has the ability to interact with remote repositories using Github API and Gitlab API. For example, you can use gitflow to create or open a PullRequest quickly in terminal.

Gitflow provides many powerful tools, such as periodically executed customized tasks, fetch or clone multiple repositories concurrently, etc. You can refer to documents for more help.

Install

Gitflow requires git 2.32.1+ and fzf 0.30.0+ installed in your machine.

Go to out release page to download the latest gitflow binary file. And then copy it to your PATH.

If you have a Go 1.19+ environment, you can build gitflow from source code:

git clone https://github.com/fioncat/gitflow /path/to/gitflow-src
cd /path/to/gitflow-src
make install

Use help to view the CLI usage:

gitflow help

Terminal Support

Binary installation is not enough, to install terminal completion and quick jump, you need to follow the instructions below according to your terminal type.

oh-my-zsh

gitflow can work as an oh-my-zsh plugin, use the following command to install the plugin:

git clone https://github.com/fioncat/gitflow ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/gitflow

Then add gitflow to your plugin list in ~/.zshrc:

# The gitflow binary MUST BE added to PATH before the plugin list.
export PATH=$PATH:/path/to/gitflow-binary

plugins=(
	gitflow
	...
)

Note that the gitflow plugin requires the gitflow binary, so the gitflow binary must already be in the PATH before the plugins list.

bash

If you are not using oh-my-zsh, you need to install gitflow terminal support manully.

First, clone the repository to your ~/.gitflow/src:

git clone https://github.com/fioncat/gitflow.git ~/.gitflow/src

Then add the following script to your bash profile, such as ~/.bashrc:

# The gitflow binary MUST BE added to PATH before loading terminal support.
export PATH=$PATH:/path/to/gitflow-binary

# To load completion support, please choose one statement according to your OS:
gitflow completion bash > /etc/bash_completion.d/gitflow # for Linux
gitflow completion bash > $(brew --prefix)/etc/bash_completion.d/gitflow # for macos

# load bash functions.
source $HOME/.gitflow/src/gitflow.sh

Note that the script to load completion is different for linux and macos.

Configuration

You need to create a gitflow config file ~/.gitflow/config.toml before using. You can also use command gitflow edit config to edit it directly.

The config file specification:

# gitflow will store all repositories under workspace.
# For exmaple, "github.com/fioncat/gitflow" will be stored to "{workspace}/github/fioncat/gitflow".
# The env value will be expended, such as "$HOME".
# Required.
workspace = "/path/to/workspace"

# The limit when searching the remote repositories.
# Optional, default is 100.
search_limit = 100

# The editor to use when using `edit` command.
# Optional, default is "vim".
editor = "vim"

# A remote represents a remote Version Control System. Such as Github, Gitlab, etc.
# Each repository belongs to a remote.
# You need to configure at least one remote.
[[remotes]]

# The unique remote name.
# Required.
name = "github"

# The remote host.
# Required.
host = "github.com"

# The clone protocol, supports "ssh" and "https".
# Optional, default is "https".
protocol = "ssh"

# The git username.
# Required.
user = "your-username"

# The git email.
# Required.
email = "your-email@example.com"

# Use to communicate with remote Version Control System. Supports "github" and "gitlab".
# Optional, if empty, many commands involving remote operations will fail.
provider = "github"

# The API token.
# Optional, if empty, some remote operations may fail due to permission reason.
token = ""

# The RESTful API url. Only work for Gitlab. If you are using a private built Gitlab,
# this is very useful. Such as "https://my-git.api.com/v4".
# Optional.
api = ""

[[groups]]
# You can configure different protocol, user and email for different groups.
prefix = "fioncat"

protocol = ""
user = ""
email = ""

Manage your repositories

Git workflow

Advanced usage