\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename forge.info
@settitle Forge User and Developer Manual
@documentencoding UTF-8
@documentlanguage en
@c %**end of header

@copying
@quotation
Copyright (C) 2018-2020 Jonas Bernoulli <jonas@@bernoul.li>

You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any
later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the GNU
General Public License for more details.

@end quotation
@end copying

@dircategory Emacs
@direntry
* Forge: (forge).       Access Git Forges from Magit.
@end direntry

@finalout
@titlepage
@title Forge User and Developer Manual
@subtitle for version 0.1.0 (v0.1.0-318-g274c3461+1)
@author Jonas Bernoulli
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Forge User and Developer Manual

Forge allows you to work with Git forges, such as Github and Gitlab,
from the comfort of Magit and the rest of Emacs.

@noindent
This manual is for Forge version 0.1.0 (v0.1.0-318-g274c3461+1).

@quotation
Copyright (C) 2018-2020 Jonas Bernoulli <jonas@@bernoul.li>

You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any
later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the GNU
General Public License for more details.

@end quotation
@end ifnottex

@menu
* Introduction::
* Supported Forges and Hosts::
* Getting Started::
* Usage::
* FAQ::
* Keystroke Index::
* Command Index::
* Function Index::
* Variable Index::

@detailmenu
--- The Detailed Node Listing ---

Getting Started

* Initial Pull::
* Token Creation::
* Repository Detection::

Usage

* Pulling::
* Branching::
* Working with Topics::
* Miscellaneous::

Working with Topics

* Visiting Topics::
* Listing Topics and Notifications::
* Creating Topics::
* Editing Topics and Posts::


FAQ

* Is it possible to create a single pull-request without pulling everything?::

@end detailmenu
@end menu

@node Introduction
@chapter Introduction

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.

@node Supported Forges and Hosts
@chapter Supported Forges and Hosts

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}.

@section Supported Forges

@itemize
@item
Github

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

Github Caveats

@itemize
@item
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.


@item
Forge depends on the @code{updated_at} field being updated when
appropriate.  For Github pull-requests at least, that is not always
done.
@end itemize

Github Hosts

@itemize
@item
@uref{https://github.com}
@end itemize


@item
Gitlab

Gitlab Caveats

@itemize
@item
Forge cannot provide notifications because the Gitlab API does not
expose those.
@end itemize

Gitlab Hosts

@itemize
@item
@uref{https://gitlab.com}

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

@item
@uref{https://framagit.org}
@end itemize
@end itemize

@section Partially Supported Forges

@itemize
@item
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}.


@item
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

@itemize
@item
@uref{https://code.orgmode.org}
@end itemize


@item
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

@itemize
@item
The API documentation is poor and initial tests indicated that the
implementation is buggy.


@item
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.


@item
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}.
@end itemize

Bitbucket Hosts

@itemize
@item
@uref{https://bitbucket.org}
@end itemize
@end itemize

@section Supported Semi-Forges

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

Gitweb Caveats

@itemize
@item
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).
@end itemize


@item
Cgit @uref{https://git.zx2c4.com/cgit/about}

Cgit Caveats

@itemize
@item
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.
@end itemize

Cgit Hosts

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

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

@item
@uref{https://repo.or.cz}
@end itemize


@item
Stgit @uref{https://codemadness.org/git/stagit/file/README.html}

Stgit Caveats

@itemize
@item
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).
@end itemize

Stgit Hosts

@itemize
@item
@uref{https://git.suckless.org}
@end itemize


@item
Srht @uref{https://meta.sr.ht}

Srht Caveats

@itemize
@item
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).
@end itemize

Srht Hosts

@itemize
@item
@uref{https://git.sr.ht}
@end itemize
@end itemize

@node Getting Started
@chapter Getting Started

Getting started using Forge should be fairly easy, but there are a few
caveats you should be aware of:

@itemize
@item
Forge uses the Ghub package to access forge APIs.  For this purpose
you have to create a token as described in @ref{Token Creation}.


@item
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}.


@item
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}.


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

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

@lisp
(with-eval-after-load 'magit
  (require 'forge))
@end lisp

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

@lisp
(use-package forge
  :after magit)
@end lisp

@menu
* Initial Pull::
* Token Creation::
* Repository Detection::
@end menu

@node Initial Pull
@section Initial Pull

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.

@node Token Creation
@section Token Creation

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.

@itemize
@item
For Github these scopes are required.

@itemize
@item
@code{repo} grants full read/write access to private and public
repositories.

@item
@code{user} grants access to profile information.

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

More infomation about these and other scopes can be found at
@uref{https://docs.github.com/en/developers/apps/scopes-for-oauth-apps}.


@item
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.
@end itemize

@node Repository Detection
@section Repository Detection

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}.

@node Usage
@chapter Usage

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
@kindex ' a
@cindex forge-add-repository
@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}.
@end table

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
@kindex '
@cindex forge-dispatch
@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.
@end table

@menu
* Pulling::
* Branching::
* Working with Topics::
* Miscellaneous::
@end menu

@node Pulling
@section Pulling

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
@kindex f y
@cindex forge-pull
@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}.

@kindex f Y
@cindex forge-pull-notifications
@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.
@end table

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
@kindex M-x forge-pull-pullreq
@cindex forge-pull-pullreq
@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}.
@end table

@node Branching
@section 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
(@code{magit-branch} on @code{b} and @code{magit-worktree} on @code{%}).

@table @asis
@kindex b Y
@cindex forge-branch-pullreq
@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:

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

@item
@code{branch.<name>.pullRequestRemote} is set to the remote on which the
pull-request branch is located.

@item
@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.

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

@item
@code{branch.<name>.rebase} is set to @code{true} because there should be no
merge commits among the commits in a pull-request.
@end itemize

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".

@itemize
@item
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.


@item
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.

@itemize
@item
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.


@item
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.


@item
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.
@end itemize

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.
@end itemize

@kindex b y
@cindex forge-checkout-pullreq
@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.

@kindex % y
@cindex forge-checkout-worktree
@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.
@end table

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.

@node Working with Topics
@section Working with Topics

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

@menu
* Visiting Topics::
* Listing Topics and Notifications::
* Creating Topics::
* Editing Topics and Posts::
@end menu

@node Visiting Topics
@subsection Visiting Topics

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
@kindex C-c C-w
@cindex forge-browse-TYPE
@item @kbd{C-c C-w} @tie{}@tie{}@tie{}@tie{}(@code{forge-browse-TYPE})
@kindex C-c C-w
@cindex forge-browse-dwim
@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.

@kindex RET
@cindex forge-visit-TYPE
@item @kbd{RET} @tie{}@tie{}@tie{}@tie{}(@code{forge-visit-TYPE})
@kindex C-c C-v
@cindex forge-visit-topic
@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}).
@end table

@node Listing Topics and Notifications
@subsection Listing Topics and Notifications

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}:

@defun forge-insert-pullreqs

This function inserts a list of mostly recent and/or open
pull-requests.
@end defun

@defun forge-insert-issues

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

@itemize
@item
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.

@end itemize

@cindex forge-toggle-closed-visibility
@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}:

@defun forge-insert-assigned-pullreqs

This function inserts a list of open pull-requests that are assigned
to you.
@end defun

@defun forge-insert-requested-reviews

This function inserts a list of open pull-requests that are awaiting
your review.
@end defun

@defun forge-insert-assigned-issues

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
@kindex ' r
@cindex forge-list-repositories
@item @kbd{' r} @tie{}@tie{}@tie{}@tie{}(@code{forge-list-repositories})

This command lists all known repositories in a separate buffer.

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

This command lists all notifications for all forges in a separate
buffer.

@kindex ' P
@cindex forge-list-pull-requests
@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.

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

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

@end table

@cindex forge-list-assigned-pullreqs
@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

@cindex forge-list-assigned-issues
@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

@cindex forge-list-requested-reviews
@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

@cindex forge-list-owned-pullreqs
@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

@cindex forge-list-owned-issues
@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

@defopt forge-owned-accounts

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

@defopt forge-owned-blacklist

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

@node Creating Topics
@subsection Creating Topics

@table @asis
@kindex ' c p
@cindex forge-create-pullreq
@item @kbd{' c p} @tie{}@tie{}@tie{}@tie{}(@code{forge-create-pullreq})
@kindex C-c C-n [on "Pull requests" section]
@cindex 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.

@kindex ' c i
@cindex forge-create-issue
@item @kbd{' c i} @tie{}@tie{}@tie{}@tie{}(@code{forge-create-issue})
@kindex C-c C-n [on "Issues" section]
@cindex forge-create-pullreq
@item @kbd{C-c C-n [on "Issues" section]} @tie{}@tie{}@tie{}@tie{}(@code{forge-create-pullreq})

This command creates a new issue for the current repository.
@end table

@node Editing Topics and Posts
@subsection Editing Topics and Posts

We call both issues and pull-requests "topics".  The contributions to
the conversation are called "posts".  The post that initiated the
conversation is also called a post.

These commands are available only from the topic buffer (i.e. from the
buffer that shows the posts on a topic).  Other commands that also
work in other buffers are available here also.  For example @code{C-c C-w} on
a post visits that post in a browser.

@table @asis
@kindex C-c C-n
@cindex forge-create-post
@item @kbd{C-c C-n} @tie{}@tie{}@tie{}@tie{}(@code{forge-create-post})
@kindex C-c C-r
@cindex forge-create-post
@item @kbd{C-c C-r} @tie{}@tie{}@tie{}@tie{}(@code{forge-create-post})

This command allows users to create a new post on an existing topic.
It opens a buffer in which the user can write the post.  When the
post is done, then the user has to submit using @code{C-c C-c}.

If the region is active and marks part of an existing post, then
that part of the post is quoted.  Otherwise and if a prefix argument
is used, then the complete post that point is currently on is quoted.

@kindex C-c C-e [on a post section]
@cindex forge-edit-post
@item @kbd{C-c C-e [on a post section]} @tie{}@tie{}@tie{}@tie{}(@code{forge-edit-post})

This command visits an existing post in a separate buffer.  When the
changes to the post are done, then the user has to submit using @code{C-c
  C-c}.

@kindex C-c C-e [on "Title" section]
@cindex forge-edit-topic-title
@item @kbd{C-c C-e [on "Title" section]} @tie{}@tie{}@tie{}@tie{}(@code{forge-edit-topic-title})

This command reads a new title for an existing topic in the
minibuffer.

@kindex C-c C-e [on "State" section]
@cindex forge-edit-topic-state
@item @kbd{C-c C-e [on "State" section]} @tie{}@tie{}@tie{}@tie{}(@code{forge-edit-topic-state})

This command toggles the state of an existing topic between "open"
and "closed".

@kindex C-c C-e [on "Labels" section]
@cindex forge-edit-topic-labels
@item @kbd{C-c C-e [on "Labels" section]} @tie{}@tie{}@tie{}@tie{}(@code{forge-edit-topic-labels})

This command reads a list of labels for an existing topic in the
minibuffer.

@kindex C-c C-e [on "Marks" section]
@cindex forge-edit-topic-marks
@item @kbd{C-c C-e [on "Marks" section]} @tie{}@tie{}@tie{}@tie{}(@code{forge-edit-topic-marks})

This command reads a list of marks for an existing topic in the
minibuffer.

Marks are like labels except that they are not shared with anyone
else.  To create a mark that topics can subsequently be marked with
use the command @code{forge-create-mark}.  Existing marks can be edited
using the command @code{forge-edit-mark}.

@kindex C-c C-e [on "Assignees" section]
@cindex forge-edit-topic-assignees
@item @kbd{C-c C-e [on "Assignees" section]} @tie{}@tie{}@tie{}@tie{}(@code{forge-edit-topic-assignees})

This command reads a list of assignees for an existing topic in the
minibuffer.

@kindex C-c C-e [on "Review-Requests" section]
@cindex forge-edit-topic-review-requests
@item @kbd{C-c C-e [on "Review-Requests" section]} @tie{}@tie{}@tie{}@tie{}(@code{forge-edit-topic-review-requests})

This command reads a list of people who you would like to review an
existing topic in the minibuffer.

@kindex C-c C-e [on "Note" section]
@cindex forge-edit-topic-note
@item @kbd{C-c C-e [on "Note" section]} @tie{}@tie{}@tie{}@tie{}(@code{forge-edit-topic-note})
@kindex M-x forge-edit-topic-note
@cindex forge-edit-topic-note
@item @kbd{M-x forge-edit-topic-note} @tie{}@tie{}@tie{}@tie{}(@code{forge-edit-topic-note})

This lets you edit your private note about a topic.

@kindex C-c C-k [on a comment section]
@cindex forge-delete-comment
@item @kbd{C-c C-k [on a comment section]} @tie{}@tie{}@tie{}@tie{}(@code{forge-delete-comment})

This command deletes the comment at point.
@end table

Creating a new post and editing an existing post are similar to
creating a new commit and editing the message of an existing commit.
In both cases the message has to be written in a separate buffer.
And then the process has to be finished or canceled using a separate
command.

The following commands are available in buffers used to edit posts:

@table @asis
@kindex C-c C-c
@cindex forge-post-submit
@item @kbd{C-c C-c} @tie{}@tie{}@tie{}@tie{}(@code{forge-post-submit})

This command submits the post that is being edited in the current
buffer.

@kindex C-c C-k
@cindex forge-post-cancel
@item @kbd{C-c C-k} @tie{}@tie{}@tie{}@tie{}(@code{forge-post-cancel})

This command cancels the post that is being edited in the current
buffer.
@end table

@node Miscellaneous
@section Miscellaneous

@itemize
@item
Key ' 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.


@item
Key ' a, forge-add-repository

This command reads a repository from the user and adds it to the
database.  The repository can be provided as URL, as a name, or in
the form OWNER/NAME@.  This is subject to @code{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
@code{forge-pull-topic}.

@end itemize

@cindex forge-add-user-repositories
@deffn Command forge-add-user-repositories

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

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

@cindex forge-add-organization-repositories
@deffn Command forge-add-organization-repositories

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

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

@cindex forge-remove-repository
@deffn Command forge-remove-repository

This command reads a repository and remove it from the local
database.
@end deffn

@cindex forge-remove-topic-locally
@deffn Command forge-remove-topic-locally

This command reads a topic and remove it from the local database.
The topic is not removed from the forge and 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 datbase that were removed
from the forge.  The only purpose of this command is to allow you to
manually clean up the local database.
@end deffn

@cindex forge-reset-database
@deffn 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.
@end deffn

@node FAQ
@appendix FAQ

@menu
* Is it possible to create a single pull-request without pulling everything?::
@end menu

@node Is it possible to create a single pull-request without pulling everything?
@appendixsec Is it possible to create a single pull-request without pulling everything?

Yes.  @code{M-x forge-add-repository} offers to add a repository to the
database without also fetching all pull-requests and issues.

@node Keystroke Index
@appendix Keystroke Index

@printindex ky

@node Command Index
@appendix Command Index

@printindex cp

@node Function Index
@appendix Function Index

@printindex fn

@node Variable Index
@appendix Variable Index

@printindex vr

@bye
