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

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 [email protected]:cli/cli.git
g remote add upstream  [email protected]: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 
        
           	} 
        
           }

Correct remote sort order

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.

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.

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"

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.

Absolutely understandable. I think having a way to configure this behaviour would go a long way. Personally I find the prompt a bit disruptive. Does git config allow external tools to piggyback on it's config? That way one could use git config to set gh cli options both for the user and per-repo. This way, one could set the default remote to use for PRs, API reqs, etc.

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?

This could be handy. Even if we had a config to set defaults, this sub command would allow users to make workflows that hit different repos via --repo $(gh owner-repo origin). Maybe alias could be (ab)used here, to make commands like gh api-origin.

Thinking about this more, I think an underlying cause is how upstream is often used to mean two different things (or sometimes both at the same time): (A) upstream is the repo you are contributing code back to, origin is otherwise an unused fork; (B) upstream is the repo you pull updates from, origin is what is actually used. (A) is what we often see for OSS projects, but (B) is common for internal projects (that may start from some existing base or template or need add customization).

I think this conversation has produced a few useful enhancements that gh could benefit from, so
I'm going to label this issue as such.

I think I'd like remotes to be more of a first class concern to gh with support in either gh or
git's configuration for denoting the roles various remotes should have for a given user.

Navigation Menu

Repository navigation

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

Describe the bug

Steps to reproduce the behavior

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Document which remote is used for :owner, :repo placeholders #2657

Description

Describe the bug

Steps to reproduce the behavior

Activity

mislav commented on Jan 8, 2021

razor-x commented on Jan 8, 2021

mislav commented on Jan 11, 2021

razor-x commented on Jan 11, 2021

vilmibm commented on Jan 28, 2021

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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