\input texinfo @c -*- texinfo -*-

Forge allows you to work with Git forges, such as Github and Gitlab,

from the comfort of Magit and the rest of Emacs.

This manual is for Forge version 0.1.0 (v0.1.0-320-g639ce512+1).

Forge allows you to work with Git forges, such as Github and Gitlab,

from the comfort of Magit and the rest of Emacs.

Forge fetches issues, pull-requests and other data using the forge's

API and stores that in a local database. Additionally it fetches the

pull-request references using Git. Forge implements various features

that use this data but the database and pull-request refs can also be

used by third-party packages.

Currently Forge supports two forges and three more forges partially.

Additionally it supports four semi-forges. Support for more forges

and semi-forges can and will be added.

Both forges and semi-forges provide web interfaces for Git

repositories. Forges additionally support pull-requests and issues

and make those and other information available using an API@.

When a forge is only partially supported, then that means that only

the functionality that does not require the API is implemented, or

in other words, that the forge is only supported as a semi-forge.

A host is a particular instance of a forge. For example the hosts

@uref{https://gitlab.com} and @uref{https://salsa.debian.org} are both instances of

the Gitlab forge. Forge supports some well known hosts out of the box

and additional hosts can easily be supported by adding entries to the

option @code{forge-alist}.

For more details about the caveats mentioned below (and some others)

also see @ref{Getting Started}.

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.

Forge depends on the @code{updated_at} field being updated when

appropriate. For Github pull-requests at least, that is not always

done.

Github Hosts

@uref{https://github.com}

Gitlab

Gitlab Caveats

Forge cannot provide notifications because the Gitlab API does not

expose those.

Gitlab Hosts

@uref{https://gitlab.com}

@uref{https://salsa.debian.org}

@uref{https://framagit.org}

Gitea @uref{https://gitea.io/en-us}

This is the next forge whose API will to be supported.

Currently no public Gitea Hosts are known to me.

The Gitea maintainers plan to create their own instance,

see @uref{https://github.com/go-gitea/gitea/issues/1029}.

Gogs @uref{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

@uref{https://code.orgmode.org}

Bitbucket

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

@uref{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: @uref{https://bitbucket.org/site/master/issues/5814}.

Bitbucket Hosts

@uref{https://bitbucket.org}

Gitweb @uref{https://git-scm.com/docs/gitweb}

Gitweb Caveats

I could find only one public installation

(@uref{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 @uref{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 on is the correct

one for a particular installation.

Cgit Hosts

@uref{https://git.savannah.gnu.org/cgit}

@uref{https://git.kernel.org}

@uref{https://repo.or.cz}

Stgit @uref{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

@uref{https://git.suckless.org}

Srht @uref{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

@uref{https://git.sr.ht}

Getting started using Forge should be fairly easy, but there are a few

caveats you should be aware of:

Forge uses the Ghub package to access forge APIs. For this purpose

you have to create a token as described in @ref{Token Creation}.

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 discard. That isn't such a huge

deal because for now the database does not contain any information

that cannot simply be fetched again, see @ref{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. Especially in closed-source software it can take years for

issues to get fixed, so I am no longer delaying the initial Forge

release because of that. If in doubt, then re-fetch an individual

pull-request to ensure it is up-to-date using the command

@code{forge-pull-pullreq}.

Some other, forge-specific, caveats are mentioned in @ref{Supported Forges and Hosts}.

Loading Magit doesn't cause Forge to be loaded automatically. Adding

something like this to your init file takes care of this:

Or if you use @code{use-package}:

To start using Forge in a certain repository visit the Magit status

buffer for that repository and type @code{f y} (@code{forge-pull}). Alternatively

you can use @code{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.

When adding the first repository from @uref{https://github.com} to your local

database you will be guided through the process of creating the API

token. For other forges as well as for other Github instances some

additional setup is required @strong{before} you can add the first repository.

See @ref{Token Creation}.

The first time @code{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 @code{remote.<remote>.fetch}, which fetches all pull-requests.

(@code{+refs/pull/*/head:refs/pullreqs/*} for Github)

@code{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.

Forge uses the Ghub package to access the APIs of supported Git

forges. How this works an how to create and store a token is

documented in @ref{Getting Started,,,ghub,}.

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.

@code{repo} grants full read/write access to private and public

repositories.

@code{user} grants access to profile information.

@code{read:org} grants read-only access to organization membership.

More information about these and other scopes can be found at

@uref{https://docs.github.com/en/developers/apps/scopes-for-oauth-apps}.

For Gitlab instances @code{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.

Ghub does @strong{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 @code{ghub.host} and other @code{FORGE.host} variables used

by Ghub. (But @code{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 @code{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 @code{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 @code{forge.remote} to the name

that you instead use for upstream remotes. If this variable is set,

then Forge uses the remote by that name, if it exists, the same way

it may have used @code{origin} if the the variable were undefined. I.e. it

does not fall through to try @code{origin} if no remote by your chosen name

exists.

Once the upstream remote has been determined, Forge looks it up in

@code{forge-alist}, using the host part of the URL as the key. For example

the key for @code{git@@github.com:magit/forge.git} is @code{github.com}.

Once information has been pulled from a repository's forge for the

first time, Forge adds two additional sections, named "Pull requests"

and "Issues" to Magit's status buffer. It is also possible to add a

repository to the local database without pulling all the data, which

is useful if you want to create a single pull-request.

@table @asis

@item @kbd{' a} @tie{}@tie{}@tie{}@tie{}(@code{forge-add-repository})

This command add a repository to the database.

It offers to either pull topics (now and in the future) or to only

pull individual topics when the user invokes @code{forge-pull-topic}.

Some of Forge's commands are only bound when point is within one of

these sections but other commands are also available elsewhere in

Magit's status buffer and/or from Magit's transient commands.

@table @asis

@item @kbd{'} @tie{}@tie{}@tie{}@tie{}(@code{forge-dispatch})

This prefix command is available in any Magit buffer and provides

access to several of the available Forge commands. Most of these

commands are also bound elsewhere, but some are not. See the

following sections for information about the available commands.

The commands that fetch forge data are available from the same

transient prefix command (@code{magit-fetch} on @code{f}) that is used to fetch Git

data. If option @code{magit-pull-or-fetch} is non-nil, then they are also

available from the @code{magit-pull} transient (on @code{F}).

@table @asis

@item @kbd{f y} @tie{}@tie{}@tie{}@tie{}(@code{forge-pull})

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 @ref{Initial Pull}.

@item @kbd{f Y} @tie{}@tie{}@tie{}@tie{}(@code{forge-pull-notifications})

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 @strong{all} topics for the respective repositories

(using @code{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 having 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.

@table @asis

@item @kbd{M-x forge-pull-pullreq} @tie{}@tie{}@tie{}@tie{}(@code{forge-pull-pullreq})

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. Especially in closed-source software it can take years for

issues to get fixed, so I am no longer delaying the initial Forge

release because of that. If in doubt, then re-fetch an individual

pull-request to ensure it is up-to-date using the command

@code{forge-pull-pullreq}.

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

(@code{magit-branch} on @code{b} and @code{magit-worktree} on @code{%}).

@table @asis

@item @kbd{b Y} @tie{}@tie{}@tie{}@tie{}(@code{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 @code{N} is the

pull-request number.

These variables are always set by this command:

@code{branch.<name>.pullRequest} is set to the pull-request number.

@code{branch.<name>.pullRequestRemote} is set to the remote on which the

pull-request branch is located.

@code{branch.<name>.pushRemote} is set to the same remote as

@code{branch.<name>.pullRequestRemote} if that is possible, otherwise

it is set to the upstream remote.

@code{branch.<name>.description} is set to the pull-request title.

@code{branch.<name>.rebase} is set to @code{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 @code{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, then 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 @code{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

@code{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 @code{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 @code{branch.<name>.pushRemote}, even

if the used value is identical to that of @code{remote.pushDefault}, just

in case you change the value of the latter later on. Additionally

the variable @code{branch.<name>.pullRequestRemote} is set to the remote

on which the pull-request branch is located.

@item @kbd{b y} @tie{}@tie{}@tie{}@tie{}(@code{forge-checkout-pullreq})

This command creates and configures a new branch from a pull-request

the same way @code{forge-branch-pullreq} does. Additionally it checks out

the new branch.

@item @kbd{% y} @tie{}@tie{}@tie{}@tie{}(@code{forge-checkout-worktree})

This command creates and configures a new branch from a pull-request

the same way @code{forge-branch-pullreq} does. Additionally it checks out

the new branch using a new working tree.

When you delete a pull-request branch, which was created using one of

the above three commands, then @code{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.

We call both issues and pull-requests "topics". The contributions to

the conversation are called "posts".

Magit's status buffer contains lists of issues and pull-requests.

Topics are ordered by last modification time. All open issues and

some recently edited and closed topics are listed.

Forge provides some commands that act on the listed topics. These

commands can also be used in other contexts, such as when point is

on a commit or branch section.

@table @asis

@item @kbd{C-c C-w} @tie{}@tie{}@tie{}@tie{}(@code{forge-browse-TYPE})

@item @kbd{C-c C-w} @tie{}@tie{}@tie{}@tie{}(@code{forge-browse-dwim})

These commands visit the pull-request(s), issue(s), post, branch,

commit or remote at point in a browser.

This is implemented using various commands named @code{forge-browse-TYPE},

and the key binding is defined by remapping @code{magit-browse-thing} (as

defined in @code{magit-mode-map)}. For commit sections this key is bound

to @code{forge-browse-dwim}, which prefers a topic over a branch and a

branch over a commit.

@item @kbd{RET} @tie{}@tie{}@tie{}@tie{}(@code{forge-visit-TYPE})

@item @kbd{C-c C-v} @tie{}@tie{}@tie{}@tie{}(@code{forge-visit-topic})

These commands visit the pull-request(s), issue(s), or repository in

a separate buffer.

The @code{RET} binding is only available when point is on a issue or

pull-request section because that key is already bound to something

else for most of Magit's own sections. @code{C-c C-v} however is also

available on regular commit (e.g. in a log) and branch sections.

This is implemented using various commands named @code{forge-visit-TYPE}

and the key binding is defined by remapping @code{magit-visit-thing} (as

defined in @code{magit-mode-map}).

By default Forge lists a subset of topics directly in the Magit status

buffer. It also provides commands to list topics and notifications in

separate buffers.

Forge adds the following two functions to @code{magit-status-sections-hook}:

This function inserts a list of mostly recent and/or open

pull-requests.

@end defun

This function inserts a list of mostly recent and/or open issues.

@end defun

User Options: forge-topic-list-limit

This option limits the number of topics listed by the above

functions.

All unread topics are always shown. If the value of this option has

the form @code{(OPEN . CLOSED)}, then the integer @code{OPEN} specifies the

maximal number of topics and @code{CLOSED} specifies the maximal number of

closed topics. IF @code{CLOSED} is negative then show no closed topics

until the command @code{forge-toggle-closed-visibility} changes the sign.

@deffn Command forge-toggle-closed-visibility

This command toggles whether the above two functions list recently

closed issues in the current buffer.

@end deffn

The following three functions are also suitable for

@code{magit-status-sections-hook}:

This function inserts a list of open pull-requests that are assigned

to you.

@end defun

This function inserts a list of open pull-requests that are awaiting

your review.

@end defun

This function inserts a list of open issues that are assigned to

you.

@end defun

The following commands list repositories, notifications and topics in

dedicated buffers:

@table @asis

@item @kbd{' r} @tie{}@tie{}@tie{}@tie{}(@code{forge-list-repositories})

This command lists all known repositories in a separate buffer.

@item @kbd{' l} @tie{}@tie{}@tie{}@tie{}(@code{forge-list-notifications})

This command lists all notifications for all forges in a separate

buffer.

@item @kbd{' P} @tie{}@tie{}@tie{}@tie{}(@code{forge-list-pull-requests})

This command lists the current repository's pull-requests in a

separate buffer.

@item @kbd{' I} @tie{}@tie{}@tie{}@tie{}(@code{forge-list-issues})

This command lists the current repository's issues in a separate

buffer.

@deffn Command forge-list-assigned-pullreqs

This command lists the current repository's open issues that are

assigned to you in a separate buffer.

@end deffn

@deffn Command forge-list-assigned-issues

This command lists the current repository's open pull-requests that

are assigned to you in a separate buffer.

@end deffn

@deffn Command forge-list-requested-reviews

This command lists pull-requests of the current repository that are

awaiting your review in a separate buffer.

@end deffn

@deffn Command forge-list-owned-pullreqs

This command lists open pull-requests from all the repositories that

you own. Options @code{forge-owned-accounts} and @code{forge-owned-blacklist}

controls which repositories are considered to be owned by you. Only

Github is supported for now.

@end deffn

@deffn Command forge-list-owned-issues

This command lists open issues from all the repositories that

you own. Options @code{forge-owned-accounts} and @code{forge-owned-blacklist}

controls which repositories are considered to be owned by you. Only

Github is supported for now.

@end deffn

This is a list of accounts that are owned by you. This should

include your username as well as any organization that you own.

@end defopt

This is a list of repository names that are considered to not be

owned by you even though they would have been considered to be owned

by you based on @code{forge-owned-accounts}.

@end defopt

@table @asis

@item @kbd{' c p} @tie{}@tie{}@tie{}@tie{}(@code{forge-create-pullreq})

@item @kbd{C-c C-n [on "Pull requests" section]} @tie{}@tie{}@tie{}@tie{}(@code{forge-create-pullreq})

This command creates a new pull-request for the current repository.