3.3 Repository Detection

Ghub does not associate a given local repository with a repository on a forge. The Forge package itself takes care of this. In doing so it ignores the Git variable ghub.host and other FORGE.host variables used by Ghub. (But github.user and other variables used to specify the user are honored). Forge associates the local repository with a forge repository by first determining which remote is associated with the upstream repository and then looking that up in forge-alist.

If only one remote exists, then Forge uses that unconditionally. If several remotes exist, then a remote may be selected based on its name.

The convention is to name the upstream remote origin. If you follow this convention, then you have to do nothing else and the remote by that name is automatically used, provided it exists and regardless of whether other remotes exist. If it does not exist, then no other remotes are tried.

If you do not follow the naming convention, then you have to inform Forge about that by setting the Git variable forge.remote to the name that you instead use for upstream remotes. For example, to use the upstream remote named "upstream":

cd /path/to/repo
git config --local forge.remote upstream

If this variable is set, then Forge uses the remote by that name, if it exists, the same way it may have used origin if the the variable were undefined. I.e. it does not fall through to try origin if no remote by your chosen name exists.

Once the upstream remote has been determined, Forge looks it up in forge-alist, using the host part of the URL as the key. For example the key for git@github.com:magit/forge.git is github.com.