On Mon, Feb 27, 2023 at 05:38:10AM +0000, James Cook wrote:
> Ted Bullock <tbullock@comlore.com> writes:
> > On 2023-02-26 6:14 p.m., Ted Bullock wrote:
> >> Hiya folks,
> >> 
> >> So I attempted to use got histedit this evening to change a significant
> >> typo in a commit message. So far, I've read through the manual on this
> >> and I'm left barely ahead but definitely without an edited commit message.
> >
> > Sorry for spamming the list with the double send.
> >
> > It took me another hour and a half of making mistakes with the histedit
> > command to finally get it to behave and adjust the repository in a sane
> > way. It was not at all obvious even when looking at the manual to make
> > the adjustment and then I mistakenly edited the wrong commit at least 3
> > times. There was woefully little UI guidance about what I was doing
> > wrong as well and what changes could be made. Of course relearning ed
> > for the umpteenth time did contribute here somewhat.

Did you use ed(1) on purpose? It is the default fallback if neither EDITOR
nor VISUAL is set in the environment. I don't seriously expect anyone to
use ed(1). When 'got commit' was first implemented at a hackathon in Ottawa
by Joshua Stein its default editor was set to /bin/ed in a tongue-in-cheek
manner and we ran with this.
At that time Michael W. Lucas had just published a new book about ed.
The default seemed appropriate to help promote this book.

Of course, ed is a disaster in terms of usability and without the historical
context our choice for ed makes very little sense. The histedit command did
not yet exist back then. Nowadays we present quite a few hints in files we
open for the user to edit. We should try to ensure that such hints do not
get missed. So I am going to switch the default to vi(1) for the next release,
and hope that will avoid some confusion going forward.

> > I did eventually read closer and find the -m option, but by then I had
> > some grasp of the scripting system.

Yes, he -m is the right tool for fixing errors in log messages.

> > 1. Why is it necessary to backup to an arbitrary point in the tree to
> > run this? From a user perspective this is weird for me, like if you want
> > me to write a program to edit the history, let me specify that in the
> > program.
> 
> This makes intuitive sense to me: you have to tell got which part of
> history you'd like to edit, by selecting a starting and ending point in
> history. The end point is the branch tip, and you choose the start point
> with got update -c. But, again, I have a head start here because I was
> already familiar with the process in hg and git.

Indeed. Many version control systems derive parts of their parameters
from context provided by a work tree. This is true for CVS, SVN, Git,
and Mercurial. So Got isn't really special in this regard. All commands
where users are expected to set up the work tree in advance for an
operation should already be documenting this requirement very clearly.
As far as I can tell that aspect of the documentation is complete.

> One minor complaint: I tried using the "edit" command, which the man
> page says will make got interrupt the process for amending. I wasn't
> entirely sure how I was supposed to amend the commit. I seem to have
> guessed right the first time, though: to "amend" the commit I actually
> have to create it again with "got ci". In other VCSs I'm used to the old
> log message being available when "amending" but it wasn't, but I guess
> that's a matter of polish. Then once I'm done I have to run got histedit
> -c. The sequence of steps (1. create script with "edit"; 2. got ci; 3.
> got he -c) is never explicitly laid out, and arguably step 2 is not
> documented at all. But I pieced it together without much trouble.

Thanks for pointing this out. I have added hints to the section of
the man page which documents the 'edit' command of the histedit script:
https://git.gameoftrees.org/gitweb/?p=got.git;a=commitdiff;h=456d8970e