Introducing gitb, a command-line tool for Backlog Git

Overview of gitb

gitb  or “Gitby” is a command-line (CLI) tool that assists git-related operations for Backlog Git.

For example, you can use a command to open the Backlog issues list in your web browser or open the list of pull requests associated with the current repository. All git commands can be executed via the gitb command, so you can use git commands too without needing to enter both. Alternatively, if you set up an alias, you can use gitb commands as a sub-command of Git, such as git pr or git issue.

gitb functions

gitb opens up a lot of new functions within the Backlog tool. Here’s a quick summary of some of the main benefits you’ll get by using it:

Open the browser to view information linked to the repository with one command
For example, you can open Backlog pages such as pull requests and issues associated with the current branch, view the list of branches in the current repository, view the list of tags, or view the commit log with just one command.

All git commands can be executed via gitb command
Since the gitb command is a wrapper of the git command, you can run git sub-commands using the gitb command, e.g. gitb pull, gitb push. This allows you to enter commands smoothly without needing to consider whether they are git or gitb commands.

Motivation for developing gitb

We, of course, use our own tool Backlog to manage our projects and source code versions, as well as dogfooding. As a developer, I create, view, and update issues and pull requests that are linked to the code repository many times a day. Each time I would open the Backlog dashboard in my web browser, I would then go to the ‘Create Issues’ or ‘Pull Request’ screens. After a while, I found the extra steps in this routine tiresome. So, I decided to make it more efficient.

Automation approach
Here’s a step-by-step breakdown of the workflow (e.g. issue creation), and how I approached the automation of it.

1. Open browser
2. Open Backlog’s dashboard from the browser’s bookmark bar
3. Select the target project from the Backlog dashboard and open the issue creation screen
4. Create an issue using the issue creation screen
5. Copy the issue key
6. Open my terminal
7. Move to the working repository
8. Create a git branch containing the issue key as the name: git checkout -b $NAME

I found it troublesome to repeat steps 1-3 (navigating the browser) every time I started working on a new development task/issue. There’s a faster way to get through the process.

Using the command-line for automation
Although there are several ways to approach the problem, I chose to use the terminal command-line tool because it is often the starting point for my day-to-day work and the most familiar to me.

Here’s the flow after automating the browser navigation steps and using gitb:

1. Open terminal
2. Move to the working repository
3. Enter command in terminal: gitb issue add — this automatically opens the issue creation screen of the target project in my browser
4. Create an issue using the issue creation screen
5. Copy the issue key
6. Return to my terminal and enter: gitb checkout -b $NAME to create a branch containing the issue key as the name

Additionally, using the Backlog API, it’s possible to create an issue using the terminal, e.g. with the command: gitb issue add –title=foo

However, I dropped this from the scope because, besides the issue title, there is a plethora of other information needed to create an issue, including issue description, assignee, milestone, due date, etc. would be difficult to input all of it with just one command.

How to install

Homebrew
You can install gitb with Homebrew, a package manager available for MacOS.

brew tap watanabe/gitb brew install gitb

Go
If you have Go language (go1.13+) installed, you can also install it using go get:

go get github.com/vvatanabe/gitb

Github Release Page

You can download the pre-built binaries for each OS from the GitHub release page. After downloading, add the directory to the path.

Basic usage of gitb

I will explain how to use gitb for frequently used Backlog functions, such as issue creation and pull requests, and other useful settings. 

For the full list of gitb commands, specific options, and arguments, feel free to refer to the gitb documentation page.

Open issue list:
gitb issue [-s, –state <STATE>] opens the Backlog issue list page for the current project. Filter issues by the <STATE> value. The value can be specified as ‘all’,  ‘open’,  ‘in_progress’,  ‘resolved’,  ‘closed’, or ‘not_closed’ (the default value).

Open an issue:
gitb issue show opens the Backlog issue page associated with the current branch.

Add an issue:
gitb issue add opens the issue creation page where you can add issues to the current project.

Open pull request list:
gitb pr [-s, –state <STATE>] opens the Backlog pull request list page of the current repository. Filter pull requests by the <STATE> value. The value can be ‘open’ (default), ‘closed’, ‘merged’, or ‘all’.

Open pull request:
gitb pr show opens the Backlog pull request page associated with the current branch.

gitb pr show [<PR-ID>] opens the pull request page for the specified <PR-ID>. When <PR-ID> is not specified, the pull request page related to the current branch is opened.

Add a pull request:
gitb pr add [-b, –base <BASE>] opens the Backlog page where you can add a pull request with the current branch as a topic branch. BASE is the branch name on which the pull request is based. The default will be empty.

View related pull requests line by line in file:
gitb pr blame [git blame command options] <PATH>

The pull request ID related to the specified <PATH> change is displayed line by line as shown below. You can also apply the options of the git blame command. This function was created by porting from kazuho/git-blame-pr.pl.

$ git pr blame -s ./main.go PR #6  55) Subcommands: []cli.Command{ PR #6  56) { PR #6  57)     Name: “show”, PR #21 58)     Usage: “Open the pull request page. When no specify <PR-ID>, open the PR page related to the current branch”, PR #6  59)     Action: func(c *cli.Context) error { PR #13 60)     repo, err := open(“.”)

If you pass in the ID of the displayed pull request as gitb pr show 55, you can immediately open the target pull request screen.

Alias ​​settings

When using the gitb command as a git command, add the following alias to .xxxrc (e.g. .bashrc, .zshrc, config.fish).

Bash, Zsh:

function git() {      gitb “$@” }

Fish:

function git      gitb $argv end

Now you can use the gitb subcommands like gitb pr and gitb issue as if they were subcommands of git itself without having to worry about entering git or gitb when using the command.

How does gitb work?

I will briefly explain how gitb works and some of its functions.

gitb itself is implemented in Golang. There are two reasons for choosing Go: It is easy to cross-compile the binaries to run on each OS and I’m familiar with it.

Internally it runs the git command to collect the necessary information, and in part uses Git’s Golang implementation, go-git.

How to open the related pull request screen
Let me take a moment to explain how gitb opens the pull request screen from the current branch.

1. Get the name of the current branch
The name of the current branch is kept in .git/HEAD in the form of ref: refs/heads/$BRANCH_NAME, so this file is parsed and retrieved. Here, suppose the current branch name is patch-3.

2. Get a list of remote references
Use the command git ls-remote to get a list of remote references (branches, tags, etc.). The list of references is tied to the commit ID at the beginning of each branch and tag, like this:

F6d550773a1cddb09bdab1c94f5c197abca9750c F6d550773a1cddb09bdab1c94f5c197abca9750c 22ee6e85764d4788a9cb5ce8762365d77b2e7688 61242c8bcea3d82321b7eaa56b5c0b484118ddcb 22ee6e85764d4788a9cb5ce8762365d77b2e7688 61242c8bcea3d82321b7eaa56b5c0b484118ddcb 2674ad54e116b4a05d933aa75c7af0657afd0079 cf1cbb47a771e136377cb24e95861485a18bcffa

HEAD refs/heads/master refs/heads/patch-1 refs/heads/patch-3 refs/pull/2/head refs/pull/4/head refs/tags/0.1.0 refs/tags/0.2.0

3. Get the commit ID at the beginning of the current branch
Get the commit ID of the current branch, patch-3 , from the list of references. 61242c8bcea3d82321b7eaa56b5c0b484118ddcb is the target here.

4. Get a pull request reference with the same commit ID as in Step 3
Get a reference for the pull request with commit ID 61242c8bcea3d82321b7eaa56b5c0b484118ddcb at the top, which is the top commit of the current branch. In the above, the target is refs/pull/4/head.

5. Get the pull request ID
The reference for pull request refs/pull/4/head is the pull request ID. In the image above, line 4 is the pull request ID.

6. Get the URL of the remote repository
The URL of the remote repository is written in .git/config in the local repository in the following format. This file is parsed and acquired. See below: https://foo.backlog.jp/git/BAR/baz.git is the URL.

[remote “origin”]         url = https://foo.backlog.jp/git/BAR/baz.git         fetch = +refs/heads/*:refs/remotes/origin/*

7. Get the host, project key, and repository name
From the URL of the retrieved remote repository, i.e. https://foo.backlog.jp/git/BAR/baz.git, get the host info: foo.backlog.jp, project key: BAR, and the repository name: baz.

8. Format URL of Backlog pull request
Assemble the pull request URL in the following format based on the host, project key, repository name, and pull request ID.

https://foo.backlog.jp/git/BAR/baz/pullRequests/4

9. Open the pull request URL
Finally, open the assembled pull request URL in the browser. 

The exec.Cmd command and URL structure are specified in the Golang standard library, and the Run() function is executed. Linux is Xdg-open, Mac OSX is open, and Windows is executed with rundll32.exe of the url.dll FileProtocolHandler.

Run git command via gitb command

In cases where the command does not apply to gitb, it’s a simple implementation that passes arguments and options to the git command.

The syscall.Exec() function of the Golang standard library is used to execute git commands for gitb, and it replaces the gitb process with the target git command. Therefore, there is no code for exchanging data between gitb and git, and it is almost the same as executing a git command directly.

However, Windows does not support the syscall.Exec() function, so it passes the standard input, output, and error output to the exec.Cmd structure and runs it as a child process in the Run() function.

Summary

Thank you for going through this explanation of the gitb command-line tool. It’s a small tool, but it has the potential to make a big difference in your everyday work. Please use its GitHub Issues page if you find any bugs to report, think of questions, or want to start community discussions.

Acknowledgment

• GitHub’s command-line tool, hub, was a great reference for implementing gitb.
• The git pr blame command was created by porting from kazuho/git-blame-pr.pl.

Thank you for taking the time to learn about this new tool!