2.1 Supported Forges

Github

Forge’s support for Github can be considered the "reference implementation". Support for other forges can lag behind a bit.

Github Caveats

• Forge uses the Github GraphQL API when possible but has to fall back to use the REST API in many cases because the former is still rather incomplete.
• The Github GraphQL API has a hard-coded timeout on queries. The only solution is to reduce the number of entities we query at once, which can be done by adjusting either the forge.graphqlItemLimit git variable or the field "GQL entity limit" in a status buffer.
• Forge depends on the updated_at field being updated when appropriate. For Github pull-requests at least, that is not always done.

Github Hosts

• https://github.com

Gitlab

Gitlab Caveats

• Forge cannot provide notifications because the Gitlab API does not expose those.

Gitlab Hosts

• https://gitlab.com
• https://salsa.debian.org
• https://framagit.org

2.2 Partially Supported Forges

Gitea https://gitea.io

This is the next forge whose API will be supported.

Gitea Hosts

• https://codeberg.org

Gogs https://gogs.io

Once Gitea is supported it should be fairly simple to support Gogs too, because the former is a fork of the latter and the APIs seem to still be very similar.

Gogs Hosts

• https://code.orgmode.org

Bitbucket https://bitbucket.org

I don’t plan to support Bitbucket’s API any time soon, and it gets less likely that I will every do it every time I look at it.

Bitbucket Caveats

• The API documentation is poor and initial tests indicated that the implementation is buggy.
• Atlassian’s offering contains two very distinct implementations that are both called "Bitbucket". Forge only supports the implementation whose only instance is available at https://bitbucket.org, because I only have access to that.
• Unlike all other forges, Bitbucket does not expose pull-requests as references in the upstream repository. For that reason Forge actually treats it as a semi-forge, not as forge whose API is not supported yet. This means that you cannot checkout pull-requests locally. There is little hope that this will ever get fixed; the respective issue was opened six years ago and there has been no progress since: https://bitbucket.org/site/master/issues/5814.

Bitbucket Hosts

• https://bitbucket.org

2.3 Supported Semi-Forges

Gitweb https://git-scm.com/docs/gitweb

Gitweb Caveats

• I could find only one public installation (https://git.savannah.gnu.org), which gives users the choice between Gitweb and Cgit. The latter seems more popular (not just on this site).

Cgit https://git.zx2c4.com/cgit/about

Cgit Caveats

• Different sites use different URL schemata and some of the bigger sites use a fork. For this reason Forge has to provide several classes to support different variations of Cgit and you have to look at their definitions to figure out which one is the correct one for a particular installation.

Cgit Hosts

• https://git.savannah.gnu.org/cgit
• https://git.kernel.org
• https://repo.or.cz

Stgit https://codemadness.org/git/stagit/file/README.html

Stgit Caveats

• Stgit cannot show logs for branches beside "master". For that reason Forge takes users to a page listing the branches when they request the log for a particular branch (even for "master" whose log is just one click away from there).

Stgit Hosts

• https://git.suckless.org

Srht https://meta.sr.ht

Srht Caveats

• Srht cannot show logs for branches beside "master". For that reason Forge takes users to a page listing the branches when they request the log for a particular branch (even for "master" whose log is just one click away from there).

Srht Hosts

• https://git.sr.ht

3.1 Loading Forge

Loading Magit doesn’t cause Forge to be loaded automatically. Adding something like this to your init file takes care of that:

(with-eval-after-load 'magit
  (require 'forge))

Or if you use use-package:

(use-package forge
  :after magit)

3.2 Token Creation

Forge uses the Ghub package to access the APIs of supported Git forges. How this works and how to create and store a token is documented in (ghub)Getting Started.

Ghub used to provide a setup wizard, but that had to be removed for reasons given in the manual just mentioned. Nowadays there is no way around reading the documentation and doing this manually I am afraid.

Forge requires the following token scopes.

• For Github these scopes are required.
  • repo grants full read/write access to private and public repositories.
  • user grants access to profile information.
  • read:org grants read-only access to organization membership.

  More information about these and other scopes can be found at https://docs.github.com/en/developers/apps/scopes-for-oauth-apps.

• For Gitlab instances api is the only required scope. It gives read and write access to everything. The Gitlab API provides more fine-grained scopes for read-only access, but when any write access at all is required, then it is all or nothing.

3.3 Initial Pull

To start using Forge in a certain repository visit the Magit status buffer for that repository and type f n (forge-pull). Alternatively, you can use M-x forge-add-repository, which makes it possible to add a forge repository without pulling all topics and even without having to clone the respective Git repository.

You must set up a token before you can add the first repository. See Token Creation.

The first time forge-pull is run in a repository, an entry for that repository is added to the database and a new value is added to the Git variable remote.<remote>.fetch, which fetches all pull-requests. (+refs/pull/*/head:refs/pullreqs/* for Github)

forge-pull then fetches topics and other information using the forge’s API and pull-request references using Git.

The initial fetch can take a while but most of that is done asynchronously. Storing the information in the database is done synchronously though, so there can be a noticeable hang at the end. Subsequent fetches are much faster.

Fetching issues from Github is much faster than fetching from other forges because making a handful of GraphQL requests is much faster than making hundreds of REST requests.

3.4 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 *.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. To reduce the number of support requests, this is even the case if the Git variable forge.remote names another, non-existent, remote.

If several remotes exist, then a remote may be selected based on its name. Almost always we want to fetch the data associated with the upstream repository, so that is what the logic described here tries to achieve. The convention is to name the upstream remote "origin", and if that convention were universally followed, then things would be trivial. However many people name the upstream remote "upstream", which also makes sense.

Note, however, that even though a surprising number of people do just that, it does not make any sense to use the name "origin" to refer to a fork; not even to your own fork. A fork is a copy of the original, "copy" is an antonym for "original", and the word "origin" is not only closely related to but even contained in the word "original". Naming a fork the "origin" is at best extremely confusing.

copy

a thing made to be similar or identical to another.

original

the earliest form of something, from which copies may be made.

origin

the point or place where something begins, arises, or is derived.

If several remotes exist, then the following remote names are tried in order and the first remote thus named that exists in the repository is used.

1. The value of the Git variable forge.remote, if set. If the variable has a value but no remote by the specified name exists, then a warning is shown, but otherwise this conflict is ignored. This behavior is arguably odd, but due to historic and pragmatic reasons it is the least painful path forward.
2. The remote named upstream, if it exists.
3. The remote named origin, if it exists.

The remote named "upstream" is preferred over the remote named "origin" because the existence of the former strongly suggests that the latter is either not used in this repository (in which case the order does not matter) or else it is abused as the name of a fork (in which case "upstream" must be preferred).

Variable: forge.remote ¶

The value of this variable specifies the remote from which Forge fetches data. It is usually best to leave this unspecified and to rely on the behavior described above.

If the remote has to be specified explicitly, then this should be done locally, for a single repository.

Only ever set this globally, if you consistently use a certain name to refer to the upstream repository and it isn’t one of "upstream" or "origin", and you never use that name to refer to a repository that does not refer to the upstream repository.

N r (forge-forge.remote) ¶

This command changes the value of the forge.remote Git variable in the current repository.

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.

User Option: forge-alist ¶

This option defines forge hosts known to Forge.

Each entry has the form (GITHOST APIHOST ID CLASS).

• GITHOST is matched against the host part of Git remote urls using forge--url-regexp to identify the forge.
• APIHOST is the api endpoint of the forge’s api.
• ID is used to identify the forge in the local database.
• CLASS is the class to be used for repository from the forge.

GITHOST and APIHOST can be changed, but ID and CLASS are final. If you change ID, then the identity of every repository from that forge changes. If you change CLASS, then things start falling apart.

There can be multiple elements that only differ in GITHOST. Among those, the canonical element should come first. Any elements that have the same APIHOST must also have the same ID, and vice-versa.

When adding a new entry, look at the default entries.

Complications:

• When connecting to a Github Enterprise edition whose REST API’s end point is "<host>/v3" and whose GraphQL API’s end point is "<host>/graphql", then use "<host>/v3" as APIHOST. This is a historic accident. See issue #174.
• This variable does not account for the possibility that the git repository does not use the same address as the web interface. That is another historic accident and if many users are affected by it, we might have to fix it properly. If you would like that, comment on issue #532.

  For now a workaround has to be used. Assuming the web interface is available at "example.com" and the repository is at "ssh.example.com", use "example.com" as GITHOST and add something like this to ".gitconfig":

  [url "git@ssh.example.com"]
      insteadOf = git@example.com"
  

3.5 Caveats

• Fetched information is stored in a database. The table schemata of that database have not been finalized yet. Until that has happened it will occasionally have to be discarded. That isn’t such a huge deal because for now the database does not contain any information that cannot simply be fetched again, see Initial Pull.
• Fetching is implemented under the assumption that the API can be asked to list the things that have changed since we last checked. Unfortunately the APIs are not bug-free, so this is not always the case. If in doubt, then re-fetch an individual topic to ensure it is up-to-date using the command forge-pull-topic.
• Some other, forge-specific, caveats are mentioned in Supported Forges and Hosts.

4.1 Pulling

The commands that fetch forge data are available from the same transient prefix command (magit-fetch on f) that is used to fetch Git data. If option magit-pull-or-fetch is non-nil, then they are also available from the magit-pull transient (on F).

f n (forge-pull) ¶

N f f

This command uses a forge’s API to fetch topics and other information about the current repository and stores the fetched information in the database. It also fetches notifications for all repositories from the same forge host. (Currently this is limited to Github.) Finally it fetches pull-request references using Git.

After using this command for the first time in a given repository the status buffer for that repository always lists the pull-requests and issues. See Initial Pull.

f N (forge-pull-notifications) ¶

N f n

This command uses a forge’s API to fetch all notifications from that forge including, but not limited to, the notifications for the current repository.

Fetching all notifications fetches associated topics even if you have not started fetching all topics for the respective repositories (using forge-pull), but it does not cause the topics to be listed in the status buffer of such "uninitialized" repositories.

Note how pulling data from a forge’s API works the same way as pulling Git data does; you do it explicitly when you want to see the work done by others.

This is less disruptive, more reliable, and easier to understand than if Forge did the pulling by itself at random intervals. It might however mean that you occasionally invoke a command expecting the most recent data to be available and then have to abort to pull first. The same can happen with Git, e.g., you might attempt to merge a branch that you know exists but haven’t actually pulled yet.

N f t (forge-pull-topic) ¶

This command uses a forge’s API to fetch a single pull-request and stores it in the database.

Normally you wouldn’t want to pull a single pull-request by itself, but due to a bug in the Github API you might sometimes have to do so.

Fetching is implemented under the assumption that the API can be asked to list the things that have changed since we last checked. Unfortunately the APIs are not bug-free, so this is not always the case. If in doubt, then re-fetch an individual topic to ensure it is up-to-date using the command forge-pull-topic.

4.2 Branching

Forge provides commands for creating and checking out a new branch or work tree from a pull-request. These commands are available from the same transient prefix commands as the suffix commands used to create and check out branches and work trees in a more generic fashion (magit-branch on b and magit-worktree on %).

b F (forge-branch-pullreq) ¶

This command creates and configures a new branch from a pull-request, creating and configuring a new remote if necessary.

The name of the local branch is the same as the name of the remote branch that you are being asked to merge, unless the contributor could not be bothered to properly name the branch before opening the pull-request. The most likely such case is when you are being asked to merge something like "fork/master" into "origin/master". In such cases the local branch will be named "pr-N", where N is the pull-request number.

These variables are always set by this command:

• branch.<name>.pullRequest is set to the pull-request number.
• branch.<name>.pullRequestRemote is set to the remote on which the pull-request branch is located.
• branch.<name>.pushRemote is set to the same remote as branch.<name>.pullRequestRemote if that is possible, otherwise it is set to the upstream remote.
• branch.<name>.description is set to the pull-request title.
• branch.<name>.rebase is set to true because there should be no merge commits among the commits in a pull-request.

This command also configures the upstream and the push-remote of the local branch that it creates.

The branch against which the pull-request was opened is always used as the upstream. This makes it easy to see what commits you are being asked to merge in the section titled something like "Unmerged into origin/master".

Like for other commands that create a branch, it depends on the option magit-branch-prefer-remote-upstream whether the remote branch itself or the respective local branch is used as the upstream, so this section may also be titled, e.g., "Unmerged into master".

When necessary and possible, the remote pull-request branch is configured to be used as the push-target. This makes it easy to see what further changes the contributor has made since you last reviewed their changes in the section titled something like "Unpulled from origin/new-feature" or "Unpulled from fork/new-feature".

• If the pull-request branch is located in the upstream repository, then you probably have set remote.pushDefault to that repository. However some users like to set that variable to their personal fork, even if they have push access to the upstream, so branch.<name>.pushRemote is set anyway.
• If the pull-request branch is located inside a fork, then you are usually able to push to that branch, because Github by default allows the recipient of a pull-request to push to the remote pull-request branch even if it is located in a fork. The contributor has to explicitly disable this.
  • If you are not allowed to push to the pull-request branch on the fork, then a branch by the same name located in the upstream repository is configured as the push-target.
  • A—sadly rather common—special case is when the contributor didn’t bother to use a dedicated branch for the pull-request.

    The most likely such case is when you are being asked to merge something like "fork/master" into "origin/master". The special push permission mentioned above is never granted for the branch that is the repository’s default branch, and that would almost certainly be the case in this scenario.

    To enable you to easily push somewhere anyway, the local branch is named "pr-N" (where N is the pull-request number) and the upstream repository is used as the push-remote.

  • Finally, if you are allowed to push to the pull-request branch and the contributor had the foresight to use a dedicated branch, then the fork is configured as the push-remote.

  The push-remote is configured using branch.<name>.pushRemote, even if the used value is identical to that of remote.pushDefault, just in case you change the value of the latter later on. Additionally the variable branch.<name>.pullRequestRemote is set to the remote on which the pull-request branch is located.

b f (forge-checkout-pullreq) ¶

This command creates and configures a new branch from a pull-request the same way forge-branch-pullreq does. Additionally it checks out the new branch.

Z n (forge-checkout-worktree) ¶

This command creates and configures a new branch from a pull-request the same way forge-branch-pullreq does. Additionally it checks out the new branch using a new working tree.

User Option: forge-checkout-worktree-read-directory-function ¶

This function is used by forge-checkout-worktree to read read the new worktree directory where it checks out to pull-request. It takes the pull-request as the only argument and must return a directory.

When you delete a pull-request branch, which was created using one of the above three commands, then magit-branch-delete usually offers to also delete the corresponding remote. It does not offer to delete a remote if (1) the remote is the upstream remote, and/or (2) if other branches are being fetched from the remote.

Note that you have to delete the local branch (e.g., "feature") for this to work. If you delete the tracking branch (e.g., "fork/feature"), then the remote is never removed.

4.3 Working with Topics

We call both issues and pull-requests "topics". The contributions to the conversation are called "posts".

• Visiting Topics
• Listing Topics and Notifications
• Creating Topics
• Editing Topics and Posts

4.4 Miscellaneous

N c f (forge-fork) ¶

This command adds an additional remote to the current repository. The remote can either point at an existing repository or one that has to be created first by forking it to an account the user has access to.

Currently this only supports Github and Gitlab.

N a (forge-add-repository) ¶

This command reads a repository from the user and adds it to the database. The repository can be provided as a URL, a name, or in the form OWNER/NAME. This is subject to magit-clone-name-alist.

This command offers to either pull topics (now and in the future) or to only pull individual topics when the user invokes forge-pull-topic.

N t t (forge-toggle-display-in-status-buffer) ¶

This command toggles whether any topics are displayed in the current Magit status buffer.

N t c (forge-toggle-closed-visibility) ¶

This command toggles whether closed topics are shown in the Magit status buffer.

Command: forge-add-user-repositories ¶

This command reads a host and a username from the user and adds all of that user’s repositories on that host to the local database.

This may take a while. Only Github is supported at the moment.

Command: forge-add-organization-repositories ¶

This command reads a host and an organization from the user and adds all the organization’s repositories on that host to the local database.

This may take a while. Only Github is supported at the moment.

Command: forge-remove-repository ¶

This command reads a repository and removes it from the local database.

Command: forge-remove-topic-locally ¶

This command reads a topic and removes it from the local database. The topic is not removed from the forge and, if it is later modified, then it will be added to the database again.

Due to how the supported APIs work, it would be too expensive to automatically remove topics from the local database that were removed from the forge. The only purpose of this command is to allow you to manually clean up the local database.

Command: forge-reset-database ¶

This command moves the current database file to the trash and creates a new empty database.

This is useful after the database’s table schemata have changed, which will happen a few times while the Forge functionality is still under heavy development.