Document which remote is used for `:owner`, `:repo` placeholders

[razor-x]

Describe the bug

When a repo has two remotes, origin and upstream, the gh api command will use upstream for :repo instead of origin. This mean API requests are sent to the wrong repo! Also affects :owner.

gh version 1.4.0 (2020-12-15)

Steps to reproduce the behavior

mkdir test-bad-remote
cd test-bad-remote
git init
g remote add origin git@github.com:cli/cli.git
g remote add upstream git@github.com:cli/oauth.git
gh api repos/:owner/:repo

Expected

{
 "full_name": "cli/cli"
 ...
}

Actual

{
 "full_name": "cli/oauth"
 ...
}

Perhaps wrong sort on the order here?

cli/context/remote.go

Lines 37 to 48 in 72eeae9

	func remoteNameSortScore(name string) int {
	switch strings.ToLower(name) {
	case "upstream":
	return 3
	case "github":
	return 2
	case "origin":
	return 1
	default:
	return 0
	}
	}

[mislav]

Hi, thank you for reporting and proposing a fix!

The current sorting logic is working as intended: the upstream remote has priority, then github, then origin, and then any other remote (in the order they appeared in git remote -v output).

The current logic is designed to address the "triangular workflow" with git where the upstream repo is pointed to by the upstream remote, and your fork has the origin remote, from which you submit PRs to upstream.

Obviously, this workflow doesn't match everyone's needs and expectations. Some people prefer to name their remotes the other way around. For interactive commands such as gh pr create, we ask users to select which is their "base" remote. But for scripting commands such as gh api, we don't ask for the base remote, and instead default to the first one found in the order of upstream, github, origin, and *.

We will be considering adding flags to select the git remote which is used for a command. But in the meantime, if you need control over which remote gets used, please do not use :owner and :repo placeholders in gh api command, but supply the values yourself.

[razor-x]

Thanks for the detailed update. I understand the sort order makes sense for the "triangular workflow" when working with all the other commands except API. But I cannot think of a case where running API commands against upstream by default would make sense. To me that is surprising and undocumented behaviour.

In your example, I would not have full API access to run command against upstream since I am not the owner of the repo.

Can you provide an expected use case for the "triangular workflow" where gh api would want to target upsteam or github over origin? Otherwise with the current behaviour, anyone using the "triangular workflow" will be unable to use gh api on their own repo (perhaps that is the expected use-case?).

Maybe we can update the docs for the gh api command to make this behaviour clear along with the suggested use-case?

Finally, I agree it would be nice if there was a way as you suggested to customize this order, or at least override for the gh api command. The :owner and :repo placeholders are very convenient since otherwise one must invent ways to "discover" them which requires extra tooling.

[mislav]

Can you provide an expected use case for the "triangular workflow" where gh api would want to target upstream or github over origin?

Yes: for example querying issues, PRs, or Releases for the project. The upstream repository will likely contain all that information, while my fork under origin will usually have none of that.

But you are right that defaulting to a single remote will not work for absolutely everyone. We've had a lot of backlash whenever we picked a new default remote for gh pr create, for example. In the end, we decided against having defaults and prompt users every time to which remote they wanted to push.

Maybe we can update the docs for the gh api command to make this behaviour clear along with the suggested use-case?

Absolutely! I've reopened an issue to track that.

The :owner and :repo placeholders are very convenient since otherwise one must invent ways to "discover" them which requires extra tooling.

Agreed. Would it be helpful to have a utility command in gh that allows you to name a remote and it outputs the owner/repo pair for that remote? Then one could do:

gh api "repos/$(gh owner-repo origin)/issues"