Make all the great features of `stg edit` more discoverable

[topher200]

Migrating discussion from #137. cc @jpgrayson

stg edit --diff can do a lot of things:

1. rename the patch
2. change the author
3. change the date
4. change the commit message
5. change the diff(!!!)

Basically, everything on the page is editable. How can we make this more discoverable?

---

The "dumb" idea would be to add instructions, similar to stg rebase --interactive or git commit.

git commit

stg rebase --interactive

---

We could drop some text in the middle of the edit message.

stg edit --diff currently:

Proposal: how about something like this?

From: Topher Green <topher@memfault.com>
Date: 2021-07-05 18:23:42 -0400

baz

---
# Everything in `edit` is editable! Modify the patch name, author, date,
# commit message and (if `--diff` was given) the diff below.

 one.txt |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/one.txt b/one.txt
index de9f81b..c70b308 100644
--- a/one.txt
+++ b/one.txt
@@ -1,4 +1,4 @@
-First line
+First line new
 Second line
 Third line
 Fourth line

I have no ego about any of this text -- happy to iterate if anyone has suggestions.

[AlansCodeLog]

Didn't realize it was so powerful. Awesome!

Regarding the message:

• Does it have to be in the middle?
• Also this part reads weird/confusing to me "Everything in edit ...". My mind immediately went to what property edit? Then I realized it was talking about the command.

I think something like this at the top is clearer:

# Everything here is editable! You can modify the patch name, author,
# date, commit message, and the diff (if `--diff` was given).
# Lines starting with # will be ignored.

For the last line, I copied the start from git, but does emptying it abort the edit like git too or ???

[topher200]

Does it have to be in the middle? Can we put it at the top?

Love that idea, very down. No reason why not.

Everything here is editable! You can modify the patch name, author, date, commit message, and the diff (if --diff was given).

I like that copy.

does emptying it abort the edit like git too?

I've got bad news here.

• Emptying the editor leaves the patch name, author, date, and commit message unchanged (since their tokens are not present in the "instruction set")
• Emptying editor destroys the commit description (sets it to an empty string).

I kind of guessed that would happen but I don't think that's very intuitive behavior. I'll take up a PR to modify this behavior to cancel on an empty editor and add an editor comment to that effect.

[AlansCodeLog]

I've never done the empty commit thing to abort to be honest. I was just thinking of the message, how similar should it be to git's.

[chucklever]

Maybe "empty editor buffer" could work the same way for "stg mail -e|-E"... if the editor buffer is empty on quit, then sending patches is canceled. Currently, you have to ^Z, "kill %1" and then remove the .swp file. Different enhancement request, perhaps.

[topher200]

Sorry, I don't think my comment was clear. I'll make a PR to modify the behavior of 'edit' to cancel everything if the editor buffer is empty on quit.

[topher200]

Does it have to be in the middle?

Thinking about this more I think that the middle is appropriate. I checked out stg new, stg rebase --interactive, stg squash, and git commit and all of them have their instructions in the middle or end. I think the reason is so that the "action" lines are at the beginning of the editor. This means that an experienced practitioner already has their cursor on the lines they're looking to edit -- they don't need to scroll past the "instructions" to get to the action lines.

I'm going to put the instruction lines in the middle (like the screenshots above) as this closest matches the behavior of git commit and stg new, which put the instruction lines between the description and the diff.