Stax

Stax is a tool that will help you to stack your PRs.

The primary purpose is to make it easier to create smaller PRs. And reduce the amount of energy other people need to review them.

Installation

MacOS

Homebrew is a package manager for MacOS.

/bin/bash -c "$(curl -fsSL https://github.com/raw/Homebrew/install/HEAD/install.sh)"

Install stax

brew install TarasMazepa/stax/stax

Windows

Chocolatey is a package manager for Windows.

Follow this guide to install chocolatey.

Install stax

choco install stax

Linux/WSL on Windows/ChromeOS

Homebrew is a package manager for MacOS that also works on Linux systems.

/bin/bash -c "$(curl -fsSL https://github.com/raw/Homebrew/install/HEAD/install.sh)"

Install stax

brew install TarasMazepa/stax/stax

Alternative

Clone this repo and put the path to the repo into your PATH variable.

stax doctor

Will help you to set up everything that stax needs to start working

stax doctor

[V] git config --get user.name # TarasMazepa
[V] git config --get user.email # 6552358+TarasMazepa@users.noreply.github.com
[V] git config --get push.autoSetupRemote # true

What is stacking PRs git workflow?

It is a way to reduce the burden of creating commits, branches, and PRs, so it doesn't consume much of your time. As a result, you can start creating more PRs with smaller changes and have them reviewed easier and faster while catching more bugs.

Commands

To see full list of commands, run:

stax help

Here is the list of commands currently available:

stax commit

Creates branch, commits current changes with the same name as a branch, and pushes.

stax commit "two-in-one-commit-name-and-branch-name"

Result:

commit 8161c952fbed66672aff80cd3d1233589cdc3c0c (HEAD -> two-in-one-commit-name-and-branch-name, origin/two-in-one-commit-name-and-branch-name)
Author: Taras Mazepa <taras.mazepa@example.com>
Date:   Fri Sep 8 14:58:04 2023 -0700

    two-in-one-commit-name-and-branch-name

You can see that a branch with two-in-one-commit-name-and-branch-name name was created as well as a commit with the same name two-in-one-commit-name-and-branch-name.

stax amend

Amends to the current commit and force pushes the branch

stax amend

stax delete-gone-branches

Deletes local branches with gone remotes. It is useful when you are using stax-commit, which pushes all the branches. So once they are merged and deleted from the remote, you can clean up local branches.

stax pull

Switching to the main branch, pulling all the changes, deleting gone branches, and switching to the original branch.

stax log

Outputs tree structure of your branches.

> stax log
  x Updates-stax-log-example-in-readme
  o Adds-stax-log-example-to-readme
o-┘ origin/main, origin/HEAD, main
| o Promotes-version-command-to-be-not-hidden-command
o-┘

stax rebase

Rebase tree of nodes on top of the /head or reference provided as first positional argument.

stax move

Move has five directions:

• up — one node up. You can optionally specify the index of the child node (as represented in the log command); the default is 0.
• down — one node up
• top — to the topmost node, but stop on the first node with more than one child. Optionally you can specify an index of the child node (as represented in log command), default is 0.
• bottom — to the bottommost node, but stop on the first node that has more than one child, or stop before the node that had /head as a child.
• head — moves to the /head

Videos

Why stack pull request?

Checking out stacking workflow

Alternatives (alphabetical order)

• https://ejoffe.github.io/spr/
• https://git-town.com/
• https://github.com/VirtusLab/git-machete
• https://github.com/arxanas/git-branchless
• https://github.com/ezyang/ghstack
• https://github.com/gitext-rs/git-stack
• https://github.com/modularml/stack-pr
• https://graphite.dev/
• https://sapling-scm.com/
• https://stacked-git.github.io/

TODO

• UI

  • Add initial console UI
  • add cd command (which will be the only way to select project)
  • add continuous stax log display

• stax

  • e2e test
    • create e2e tests roadmap
    • add more e2e tests
  • unit tests
    • create unit tests roadmap
    • add more e2e tests
  • add test coverage reporting
  • integration with gh tool (to create PRs and add automerge)
  • add update prompt (check VERSION file in repository, and offer to run choco update or brew update)

• stax move

  • flag to ignore /HEAD transition
  • flag to ignore multi children nodes

• stax squash

  • command which ensures that each branch only has one commit

• stax commit

  • perform git fetch -p before and target new commit to local branches only
  • offer stax rebase -m in case when one of the child branches are gone

• homebrew-stax

  • add test for installing stax on arm64 linux