Repository navigation
Unclear message about base repository when creating a PR #2090
Description
I suppose this has recently changed in #1706. The current prompt is confusing to me:
$ gh pr create
? Which should be the base repository (used for e.g. querying issues) for this directory? [Use arrows to move, type to filter]
> liberapay/liberapay.com
waldyrious/liberapay.comThere are two issues here:
- I am not sure what "base repository" means here; my mental model when creating a PR is one of "source" (e.g. my fork) and "target" (e.g. upstream), and I could interpret "base" as referring to either of these.
- It's not clear what "for this directory" means. I would expect something like "...for this PR", but I guess something different is being asked here, and the message doesn't tell me what.
Activity
waldyrious commentedon Oct 4, 2020
Note: I had erroneously committed to
masterinstead of to a feature branch before creating this PR — I suppose that may be why I saw this message. Regardless,ghdidn't help me figure this out, but instead confused me further; so I suppose the message could be clarified.samcoe commentedon Oct 5, 2020
@waldyrious Thank you for the feedback, I can understand how the messaging can be confusing. There is definitely room for improvement in the
pr createmessaging and we will take your feedback into account as we continue to iterate on this feature. 🙇mislav commentedon Oct 5, 2020
@waldyrious Thank you for the feedback!
The concept of a "base" repository is not just specific to the
pr createcommand, but to most other commands. The "base" repository is the GitHub repo where the majority of the maintenance happens; i.e. PRs get submitted to it, issues get filed in its issue tracker, Releases get created in it, and so on.We weren't sure how we could name it more descriptively, but if you or anyone has suggestions, we're all ears.
waldyrious commentedon Oct 5, 2020
Thanks for the context. I would say that meaning of "base" you describe matches what I'd intuitively call an "upstream", "canonical", "primary"/"main", or "original" repository. These are just from the top of my head, so I'd be happy to contribute to discussions in case these have shortcomings I might be overlooking.
vilmibm commentedon Oct 22, 2020
Switching away from "base" here makes sense to me since "base" means something in
gitterms. I like the idea of "primary". @ampinsk do you have thoughts?ampinsk commentedon Oct 29, 2020
This is a tough one, but I'm partial to
main. This may be tough to find a word that makes sense to 100% of people. I also feel that the parenthetical in the middle of the prompt makes the prompt more difficult to read. If we want to give an example, I think we could list it at the end.Could this make more sense?
waldyrious commentedon Oct 29, 2020
I think the "and submitting PRs" definitely helps, as well as the removal of "for this directory" (was that intentional?).
Here's a thought: why not simply remove "as the base" from the sentence? And maybe also switching "a repository" to "the repository":
ampinsk commentedon Oct 29, 2020
@waldyrious I like that! Thanks for the copyediting help 😄 The only lingering problem with this is that querying issues and submitting PRs aren't the only things that selecting the "base" repository affects. It also affects querying PR lists, creating issues, etc. Basically all read/write operations. So to avoid listing out every single thing this decision means, we do need some general way to talk about this concept 🤔
waldyrious commentedon Oct 29, 2020
In that case, how about something like this?
ampinsk commentedon Nov 5, 2020
@waldyrious I like that! I think it's clearer than what we have today 👍
zigang93 commentedon Dec 3, 2020
I also confuse at the first place..
samestep commentedon May 11, 2021
Just chiming in here since I was also confused by this message when running
gh pr checkoutfor the first time. Is there a reason @waldyrious's suggestion hasn't already been incorporated (as of version 1.9.2)?mislav commentedon May 11, 2021
@samestep No real reason except inertia. But, we are planning to do improvements around the "base repo" experience that go beyond just renaming the prompt.
bhajneet commentedon Aug 9, 2021
Honestly if you just removed the word base it would make so much more sense. Or renaming base to "default".
Current:
Proposed:
1dancook commentedon Nov 24, 2021
This really confused me today. I just started using gh and I ended up selecting my fork -- which made a PR a to my fork and since I referenced an issue in the project repo github a reference in that issue to the PR in my fork! 🤣🤣
Some other ideas for wording it:
Apart from that, it would be good if the explanation was written out in the help. At first I cancelled what I was doing and looked in
gh pr create --helpbut there was no good explanation there for what base meant.My other issue that I came looking for was that after I selected the wrong one (my fork) I couldn't change it (or it wasn't obvious how to do so anyway). So I had to start over from scratch. If there is a way someone please tell me. 😎
mislav commentedon Nov 24, 2021
Sorry for the nuisance! #2300 (comment)
darcyclarke commentedon Mar 16, 2022
As a quick update here, there's work being done to improve/clarify base repositories here: #4859
Griffin641498 commentedon Apr 22, 2022
JohSteph890 commentedon Oct 10, 2022
mislav commentedon Dec 22, 2022
Thanks all for your feedback. In the latest release we replaced the "base repository" prompt with a dedicated command
gh repo set-defaultwhich should be clearer. Please leave your feedback about new functionality here; thank you! #6777waldyrious commentedon Dec 24, 2022
Thanks for addressing this! I've left a comment in the discussion.