git-stk 0.1.0

Git-native stacked branch workflow helper
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

# git-stk

> Git-native stacked branch workflow helper with GitHub and GitLab review integration.

---

`git-stk` keeps stacks as ordinary Git branches. Stack parent metadata is stored locally in `.gitconfig` as
`branch.<name>.stackParent`, and GitHub PR bases or GitLab MR target branches can be used to reconstruct that metadata.

## Status

This project is experimental. The current implementation focuses on local stacked branch workflows plus
provider-backed review lookup, sync, submit, and cleanup. It does not replace Git's branch model or
attempt automatic conflict resolution.

## Install For Development

```sh
just install
just check
cargo install --path .
```

After installation, Git can use the binary as a sub-command:

```sh
git stk list
```

## Commands

Local stack metadata:

```sh
git stk new <branch>
git stk parent [branch]
git stk children [branch]
git stk list
git stk adopt <branch> --parent <parent>
git stk detach [branch]
```

Navigation and re-stacking:

```sh
git stk up
git stk down [branch]
git stk restack [--update-refs | --no-update-refs]
git stk continue
git stk abort
```

Provider-backed workflows:

```sh
git stk provider
git stk status [branch]
git stk review [branch]
git stk sync [branch] [--dry-run]
git stk submit [branch] [--dry-run]
git stk submit --stack [--dry-run]
git stk cleanup [branch] [--dry-run] [--delete-branch]
```

## Providers

Provider detection uses `stack.provider` first, then `stack.remote`, then `origin`:

```sh
git config stack.provider github  # or gitlab
git config stack.remote origin
```

GitHub support shells out to `gh`. GitLab support shells out to `glab`. Authenticate those CLIs before using provider
commands.

## Re-stacking

`restack` follows Git's `rebase.updateRefs` config by default. Use `--update-refs` or `--no-update-refs` to override that
for one run. If a rebase conflicts, `git-stk` records state in `.git/stack-state`; resolve conflicts and run
`git stk continue`, or run `git stk abort`.

## Generated Assets

Shell completions and a `man` page can be generated with:

```sh
just generate-assets
```

Generated files are written under `target/generated`.

## Project Tasks

```sh
just build
just test
just lint
just check
```

## License

Copyright (c) 2026 [Lara Kelley](https://larakelley.com). MIT License. See [LICENSE](./LICENSE).