https://linen.dev logo
Join Slack
Powered by
This message was deleted.
# how-do-i
s
This message was deleted.
❤️ 1
t
gt split
makes me inherently nervous the first time because it's a rather destructive operation that might impact an in-flight PR, so giving the user confidence in their understanding of this feature is very important.
In my case, the lack of clarity was around ordering — i had a PR open already and i wanted to pull a couple lines out into its own PR, but also keep my existing PR. What's unclear from the docs alone what, exactly, i needed to do. • I got that i needed to stage changes for one part of the split • I didn't know if I needed to stage changes for my existing PR first (you don't — it's arbitrary; the matching branch name is what matters)
p
Hey Tyler! Not open source, but please send over any improvements you have and I can add them in!
d
i'm doing docs updates this week anyway
❤️ 2
however, our CLI argparse library makes it surprisingly challenging to customize the 
--help
pages i think the more docs we write for the 
gt split --help
, it all gets dumped into the main list of commands too, so i'm looking into how to get more detailed docs on the actual help page for a command + short-description of a command on the main 
--help
page
@Tyler Nieman can you describe exactly what you were trying to do? i hear you're trying to pull out 2 lines into its own PR - did you want the new PR upstack from the current one, or downstack?
t
Here's my situation: • I had an existing branch/pr. • I discovered and fixed an unrelated bug within that branch/pr. • I then wanted to pull the bug out so it could be reviewed/merged on its own while I finished my original branch/pr. > did you want the new PR upstack from the current one, or downstack? • I wanted the smaller/new branch to get merged before my original branch/pr. • ⤴️ Because of the way I did it (staged for existing branch first, then staged the second), i had to do an additional 
gt move
on the new (bugfix) branch to move it back to trunk. • I didn't need the bugfix in my original branch; it didn't need to be a dependency to the original branch, it was just an incidental bug that i noticed along the way. Let me know if you'd like any more details on the situation @David Balatero
Also fwiw — i feel that docs on the website are more important than the CLI. They serve as onboarding for prospective, new, and veteran users — and they're linkable to other teammates.
👍 1
d
website command docs sync from 
gt --help
, jfyi
in terms of command references
t
Yes for CLI reference, but no for tertiary materials like https://graphite.dev/docs/squash-fold-split
d
yep makes sense
t
My hierarchy of docs importance is probably: 1. long-form docs 2. CLI reference (quick explainer + link to long-form docs) 3. CLI 
--help
d
yep, i am working on all 3 of those things in various ways
👍 1
i can take a note to look at 
gt split
gt split
is one of those "there's 5 ways to do it" things
t
Absolutely, it's a powerful feature but highly contextual depending on what you're trying to do. ^ even saying that in the docs would be helpful. It's not clear that it's a very dynamic command at the moment.
d
for example, if you already have two commits but they're out of order (feature commit, then bug fix, and you want to invert) you can 
gt modify --interactive-rebase
reorder the commits then do a simple 
gt split
by commit
or, you could rewind the branch with vanilla git, create 2 commits from scratch with 
git add -p
, then 
gt split
by commit
or, or, or (etc)
ultimately we need a bunch of scenarios + recipes in the docs
👍 1
you asked about open source - if you wanted to contribute to the docs i'd be happy to take + edit! but currently they are not easy to contribute to in OSS 🙂
t
100% — lots of detail on the complexity, scenarios, recipes/guidance would be helpful. Long term, a 
gt split
"wizard-y" approach might be interesting — probe for what they're trying to do, help narrow the path.
Much appreciated! For what it's worth, here's the rough notes I wrote on it for my own reference / sharing with my team: > ## 
gt split
> if you're already on a branch that has a PR and you just wanna split it into multiple branches/PRs, you can do this...
Copy code
# assuming you have 1 commit in your branch
$ gt split
# otherwise use --by-hunk or --by-commit

# you will now be in an interactive CLI.
# stage all changes that will be in one of your splits.
# after you have marked each change, you write a commit about those staged changes.
# after you have written the commit about that first split, you name the branch that the commit will be in...
# ... you can re-use your existing branch name
# ... *or* you can pick a new name for different changes
# if you re-use the branch name and it already has a PR, the new PR points to that branch - so it's important that you staged the correct files when re-using the name.
Emphasis on these being rough — they're serviceable, but not great.
I'll also note that the order that the things occur kinda threw me off as I worked through it the first time — i was thinking things like: • what am i staging for? • if i stage this, will it end up in the new branch or my old one? • why do i write the commit before choosing the branch? • what will happen to all of the things i don't stage? • do all unstaged changes end up in a singular new branch? • how many branches can i produce with a singular 
gt split
?
p
Hey Tyler, this feedback has been noted! We'll look into updating the docs soon
🙏 1
👍 1
Open in Slack
PreviousNext
Powered by