Page MenuHomeFreeBSD

git-arc: Try to improve documentation
Needs ReviewPublic

Authored by markj on Mon, Dec 29, 8:39 PM.
Tags
None
Referenced Files
F141062565: D54405.id.diff
Wed, Dec 31, 9:33 AM
Unknown Object (File)
Tue, Dec 30, 2:49 AM

Details

Reviewers
jrm
Group Reviewers
srcmgr
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.

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Skipped
Unit
Tests Skipped
Build Status
Buildable 69509
Build 66392: arc lint + arc unit

Event Timeline

markj requested review of this revision.Mon, Dec 29, 8:39 PM
ziaee added inline comments.
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.

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 added inline comments.
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.

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.