Stacked Git

Stacked Git, StGit for short, is an application for managing Git commits as a stack of patches.

With a patch stack workflow, multiple patches can be developed concurrently and efficiently, with each patch focused on a single concern, resulting in both a clean Git commit history and improved productivity.

The stg command line tool provides commands to quickly and safely manage a stack of patches.

• Apply and unapplied patches from the stack using push, pop, and goto.
• Incorporate changes from the working tree into a patch and edit patch metadata using refresh and edit.
• Create and delete patches on the stack using new, delete, and clean.
• See information about the stack or individual patches using series and show.
• Migrate patches to regular commits and vice versa using commit and uncommit.

Patch-stack management operations are performed using Git commands and the patches are stored as Git commit objects, allowing easy merging of the StGit patches into other repositories using standard Git functionality.

StGit is licensed under the GNU General Public License, version 2.

2021-04-30: StGit v1.1 has been released.

The marquee feature of StGit 1.1 is preliminary support signed patches. StGit now respects Git’s commit.gpgsign configuration option to create signed patches (commits).

This release also contains several minor new features and a few key bug fixes. See the changelog for all the details.

2021-02-07: StGit v1.0 has been released.

The 1.0 release has been over a decade in the making. While light on new features, this release represents a major upgrade in StGit’s foundation.

Internally, StGit now maintains all metadata in Git objects. This enables novel workflows involving StGit stacks to be pushed and pulled from remote repositories using git push and git pull.

And StGit has been fully migrated to Python 3. Dropping compatibility with Python 2 has allowed StGit’s code to become simpler and avoid error-prone compatibility code. Python 3.5 is the new minimum required version.

See the changelog for more details.

2020-06-12: StGit v0.23 has been released.

Why Stacked Git?

The stack of patches model is a natural way to maintain a clean Git history while working on several changes concurrently. A stack-oriented workflow using StGit can compliment, or even replace, many Git workflows involving rebase, branches, amended commits, and stashes.

StGit, via the stg command line tool, provides commands to quickly and safely create, push, pop, refresh, and reorder patches.

Installation

Dependencies

StGit is written in pure Python with no third-party Python dependencies. StGit currently supports Python version 3.5 through 3.9. The last version of StGit to support Python 2 was v0.23.

StGit interoperates closely with Git and does most of its work by running git commands. Git 2.2.0 or newer is required.

Package Repositories

Recent versions of StGit are available via many package repositories such as HomeBrew and for many Linux distributions including: Alpine, Arch, Fedora, Nix and Ubuntu.

More details about StGit packages availability for various operating systems can be found on repology.

Source Installation

StGit may also be installed from source. Download the latest release or clone from the StGit repository on GitHub.

git clone https://github.com/stacked-git/stgit.git

To install from source, choose a prefix and:

make prefix=/usr/local install install-doc

For more information about installation, see the INSTALL file.

Getting Started

This quick example of using StGit gives an idea of a basic StGit workflow using basic commands such as stg push, stg pop, and stg refresh.

For a more complete guide to using StGit, see the tutorial.

StGit also comes with a complete set of man pages which are also available online.

Project Details

StGit source code is hosted on GitHub.

Maintainers

StGit is maintained by Pete Grayson and Catalin Marinas.

Contributions

Issues and feature requests may be reported on the StGit issue tracker.

Pull requests are welcome and may be submitted to the repo on GitHub.

See CONTRIBUTING.md for more details about how to contribute to StGit.

Mailing List

For questions or discussion, please send email to the StGit mailing list. Or use the Google Groups web interface.

Historical

The StGit project was originally hosted at gna.org. That site is no longer available, but a snapshot remains available via the Wayback Machine.

Other Patch Stack Tools

StGit is not the first or only patch stack tool. Both Quilt and Mercurial's mq extension offer similar interfaces for managing a stack (or "queue" or "series") of patches. While Quilt operates on patches outside the context of any other version control system using GNU diff, the mq extension is part of the Mercurial version control system.

Similar to mq's relationship to Mercurial, StGit is tightly coupled to Git. StGit keeps its stack metadata as objects in the git repo and patches themselves are git commits.

Acknowledgements

Many thanks to Peter Grayson, Karl Wiberg, Yann Dirson, Chuck Lever and Paolo “Blaisorblade” Giarrusso for their great contribution to the development of StGit. Many thanks to all the people who contributed patches, ideas or reported bugs.

© 2021 Stacked Git Authors