is it common practice to run

gt create

then a series of

gt modify

commands afterwards for iterative changes? if so, is it recommended to amend or commit when using

gt modify

? i read somewhere that a stack should always be in a test-passing state.

I do the same, many small commits in whatever local state I have. Then I do

gt squash

prior to publishing the PR To make it easier on reviewers, I avoid the

gt squash

once they start reviewing the PR and manually squash to the latest pushed commit when addressing the PR comments

After getting comfortable with gt a bit more, this is the workflow I've settled up on & shared with the team: Making changes

gt sync  # pushes, pulls, and rebases all relevant branches
gt co  # gt checkout, interactively lets you chose the parent stack for the next set of changes

# make changes
gt c  # gt create, don't bother with branch names. similar to git branch && git commit

# make more changes if needed until compiling & tests passing, then run
gt m -ca  # gt modify --all --commit, prompts for commit message will add a commit to the current stack. similar to git commit

# submit changes for review
gt s  # gt submit, submits a pr, go request reviewers

# start from top again

Editing mid-stack

gt sync && gt co  # gt checkout, checkout the stack in question
# make relevant changes
gt m -ca  # gt modify, commit the changes
gt s  # gt submit, pushes new changes

thanks for sharing! this is really helpful feedback 🙂 fwiw the workflow you described is more-or-less the workflow that i use day to day we’re working on documenting the core flows that folks use and making them immediately accessible from various surfaces in graphite — stay tuned for more on that soon! cc @Pranathi Peri @David Balatero

@Nathan Flurry would this doc have helped you? https://gist.github.com/dbalatero/67b7e0063a3121043a039cc5f2f5bf25

@David Balatero gonna drop a bunch of nits as I go through this, I hope the fresh eyes are helpful. I appreciate that this guide doesn't try to teach all the shorthands while learning the concepts. one of the youtube videos i was trying to learn from was confusing because it was talking about concepts, shorthands, and git passthroughs all at the same time . Would be interesting to have a toggle for "full/shorthand" to show the shorthand version of the code snippets. I think there's a disconnect between "Creating a first pull request" and "Stacking a second pull request" where you use a branch name in the ``gt checkout your_first_pr_branch_name` step, but branch names are never referenced in the first pr so it leaves me wondering where the branch name gets chosen. Might be helpful to add a note that a branch name is automatically chosen.

git create -am

is clear for anyone who has worked with git and is used to the single letter flags, but most jr engineers i run across would be confused by this syntax. I might be missing something: why is the

--stack

flag required on

gt submit --stack

for pr #2? there's no descendants of the pr yet.

gt stack --submit

differs from the

gt stack submit

command shown in

gt stack --help

and differs from the

gt submit

syntax used in the previous code block. Confusing, even though they're all doing the same thing. Under "Merging your stack", I would link the phrase "top of the PR" to your glossary. Another misc idea – if you publish the

--help

output to the website somewhere, it might be nice to be able to click on a command to get more details about it. There's a lot of documentation and most of it uses the CLI syntax differently, so even though I only really need to learn 3-5 commands to get up and running, it feels like a lot more (in addition to how stacking works overall). Honestly, less and more guided docs would be very helpful. Last thing – it's sometimes helpful to see the output from the command line instead of just the commands I'm putting in.

thanks! i can make these edits. this is very helpful info