restack

README

restack

restack augments the experience of performing an interactive Git rebase to make it more friendly to workflows that involve lots of interdependent branches.

For more background on why this exists and the workflow it facilitates, see Automatically Restacking Git Branches.

Installation

Use one of the following options to install restack.

• If you use Homebrew on macOS or Linuxbrew on Linux, run the following command to download and install a pre-built binary.

  brew install abhinav/tap/restack
  

• If you use ArchLinux, install it from AUR using the restack-bin package package for a pre-built binary or the restack package package to build it from source.

  git clone https://aur.archlinux.org/restack-bin.git
  cd restack-bin
  makepkg -si
  

  With an AUR helper like yay, run the following instead:

  yay -S restack-bin # pre-built binary
  yay -S restack     # build from source
  

• Download a pre-built binary from the GitHub Releases page and place it on your $PATH.

• Build it from source if you have the Go toolchain installed.

  go install github.com/abhinav/restack/cmd/restack@latest
  

Setup

restack works by installing itself as a Git sequence.editor. You can set this up manually or let restack do it for you automatically.

Automatic Setup

Run restack setup to configure git to use restack.

restack setup

Manual Setup

If you would rather not have restack change your .gitconfig, you can set it up manually by running:

git config sequence.editor "restack edit"

See restack edit --help for the different options accepted by restack edit.

Usage

restack automatically recognizes branches being touched by the rebase and adds rebase instructions which update these branches as their heads move.

The generated instruction list also includes an opt-in commented-out section that will push these branches to the remote.

For example, given,

o master
 \
  o A
  |
  o B (feature1)
   \
    o C
    |
    o D (feature2)
     \
      o E
      |
      o F
      |
      o G (feature3)
       \
        o H (feature4, HEAD)

Running git rebase -i master from branch feature4 will give you the following instruction list.

pick A
pick B
exec git branch -f feature1

pick C
pick D
exec git branch -f feature2

pick E
pick F
pick G
exec git branch -f feature3

pick H

# Uncomment this section to push the changes.
# exec git push -f origin feature1
# exec git push -f origin feature2
# exec git push -f origin feature3

So any changes made before each exec git branch -f will become part of that branch and all following changes will be made on top of that.

Credits

Thanks to @kriskowal for the initial implementation of this tool as a script.

FAQ

Can I make restacking opt-in?

If you don't want restack to do its thing on every git rebase, you can make it opt-in by introducing a new Git command.

To do this, first make sure you don't have restack set up for the regular git rebase:

git config --global --unset sequence.editor

Next, create a file named git-restack with the following contents.

#!/bin/bash
exec git -c sequence.editor="restack edit" rebase -i "$@"

Mark it as executable and place it somewhere on $PATH.

chmod +x git-restack
mv git-restack ~/bin/git-restack

Going forward, you can run git rebase for a plain rebase, and git restack to run a rebase with support for branch restacking.

Documentation

Index

• Constants
• type Branch
• type Edit
  • func (e *Edit) Run(ctx context.Context) (err error)
• type Git
• type GitRestacker
  • func (r *GitRestacker) Restack(ctx context.Context, req *Request) error
• type Request
• type Restacker
• type Setup
  • func (s *Setup) Run(ctx context.Context) error
• type SystemGit
  • func (*SystemGit) ListBranches(ctx context.Context) ([]Branch, error)
  • func (g *SystemGit) RebaseHeadName(ctx context.Context) (string, error)

Constants

const Version = "0.5.4"

Version is the version of restack currently being used.

Note that semantic versioning in this repository applies to the `restack` executable, not to its library components. These APIs may break at any time without warning.

Types

type Branch

type Branch struct {
	Name string
	Hash string
}

Branch refers to a Git branch.

type Edit

type Edit struct {
	// Editor to use for the file.
	Editor string

	// Path to file containing initial rebase instruction list.
	Path string

	Restacker Restacker

	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

Edit implements the "restack edit" command.

func (*Edit) Run

func (e *Edit) Run(ctx context.Context) (err error)

Run runs the "restack edit" command.

type Git

type Git interface {
	ListBranches(ctx context.Context) ([]Branch, error)

	// RebaseHeadName returns the name of the branch being rebased or an empty
	// string if we're not in the middle of a rebase.
	RebaseHeadName(ctx context.Context) (string, error)
}

Git provides access to git commands.

type GitRestacker

type GitRestacker struct {
	// Controls access to Git commands.
	//
	// This field is required.
	Git Git
}

GitRestacker restacks instruction lists using the provided Git instance.

func (*GitRestacker) Restack

func (r *GitRestacker) Restack(ctx context.Context, req *Request) error

Restack process the provided instruction list.

type Request

type Request struct {
	// Name of the git remote. If set, an opt-in section that pushes restacked
	// branches to this remote will also be generated.
	//
	// This field is optional.
	RemoteName string

	// Input and output instruction lists.
	From io.Reader
	To   io.Writer
}

Request is a request to process a rebase instruction list.

type Restacker

type Restacker interface {
	Restack(context.Context, *Request) error
}

Restacker processes the rebase instruction list.

type Setup

type Setup struct {
	PrintScript bool

	Stdout io.Writer
	Stderr io.Writer
}

Setup is the "restack setup" command.

func (*Setup) Run

func (s *Setup) Run(ctx context.Context) error

Run runs the setup command.

type SystemGit

type SystemGit struct {
	Getenv func(string) string
}

SystemGit uses the global `git` command to perform git operations.

func (*SystemGit) ListBranches

func (*SystemGit) ListBranches(ctx context.Context) ([]Branch, error)

ListBranches implements Git.ListBranches.

func (*SystemGit) RebaseHeadName

func (g *SystemGit) RebaseHeadName(ctx context.Context) (string, error)

RebaseHeadName implements Git.RebaseHeadName.