git-arc: Try to improve documentation

[markj]

Summary

When I originally wrote git-arc, the usage string was the documentation.
Later, a man page was added, largely copied from the usage string. Over
time they have diverged slightly.

It is silly to have two copies of the same information, so let's make
the man page the source of truth.

While here, document some options for git-arc-patch and rewrite a few
sentences here and there in a way that I hope is clearer.

[ziaee]

tools/tools/git/git-arc.1

222

OT: Why is it HEAD:main?

I use git push freebsd main.

Also @jrtc27 taught me you can use @ instead of HEAD, and it's a lot more ergo because you usually need a tilde and it's right there.

[imp]

tools/tools/git/git-arc.1

222

HEAD:main works if these commits aren't on 'main' in the local repo, so is a safer pattern. It's also the pattern that git guides use.

As for @ vs HEAD, I'm agnostic. I didn't know that was possible.

[jrm]

tools/tools/git/git-arc.1

63–65

It's handy for ports work too. :)

78–84

Optional word-smithing.

87–88

Grammar nit. This is a comma splice (two independent clauses joined by a comma).
I had an IRC conversation with @jhb about this. Please correct me if I'm wrong, but I believe any ref would be valid, so I attempted to imply that.

@jhb was concerned that listing branch names could cause confusion.

just want to avoid people thinking that naming a branch
creates reviews for all commits on that branch
becasue it doesn't, it just creates a review for the commit at the end that matches the branch name

I added a second sentence to address those concerns.

121

Should we omit src? I guess this works with any tree.

139

Grammar nits. Feel free to ignore if they are annoying.

[ziaee]

tools/tools/git/git-arc.1

63–65

I also use it on the docs tree!

121

We could say 'source tree'?

222

Oh I see. Thanks. I always (from $branch) alias gpfm=git pull freebsd main; alias gsw=git switch to main, alias grb=git rebase $branch.

If it anything complex I'll push to origin (my GitHub) first and then alias gf=got fetch --all and alias gwd=git status to make sure that I'm $intended_commits_number commits ahead

It's a bit labor intensive, but I'm afraid of accidentally pushing drafts.

[markj]

Apply review comments from jrm.

[markj]

Thanks for the feedback.

tools/tools/git/git-arc.1

87–88

I took your suggestion and added a reference to git-rev-parse.1, which I think has the canonical documentation on this stuff (in the SPECIFYING REVISIONS section specifically).

[ngie]

tools/tools/git/git-arc.1

66–67

I think what @markj was implying is that it's not general purpose/shouldn't be used with other Phabricator instances, like [legacy] LLVM, etc.

127

(picking a line)
Is there a best practice for referencing programs which lack manpages using mandoc, like arc?

[ngie]

tools/tools/git/git-arc.1

67–76

I would probably short-circuit the package suggestion to devel/freebsd-git-devtools in the common path; I doubt folks would be installing the dependencies piecemeal (and even if they were, it probably wouldn't be a great user experience).

[ziaee]

tools/tools/git/git-arc.1

127

Yes, it's .Sy according to the extended documentation

• https://mandoc.bsd.lv/mdoc/style/commands.html

[adrian]

thanks for pushing forward documentation updates!

[markj]

tools/tools/git/git-arc.1

67–76

I know there are a few brave folks using this script on non-FreeBSD systems, where freebsd-git-devtools doesn't exist, so it's probably helpful to explicitly list the dependencies somewhere.