Function: forge-get-repository

forge-get-repository is a byte-compiled function defined in forge-core.el.

Signature

(forge-get-repository DEMAND)

Documentation

Return a forge repository object or nil, or signal an error.

A forge repository is a repository hosted on a forge. The local clone is also a "repository", but it is a "Git" repository, not a "Forge" repository. (Forge repositories are also Git repositories, but not the other way around.)

A :known repository has an entry in the local database. All other repositories are unknown. :known repositories are divided into two subgroups: :tracked and "untracked" repositories.

A :tracked repository was previously explicitly added to the database by the user.

When Forge encounters a repository, without being instructed by the user to track it, it may nevertheless add limited information about it to the database. Such a repository is :known but it is not :tracked.

Other repositories are "unknown". Most commands can only deal with repositories that are stored in the database. Of these, some can deal with any :known repositories, others require that they are :tracked.

Some other commands exist — such as the browse commands — that have no such requirement. While such commands also require a repository object, they do not care whether that is stored in the database. Instead they are happy to use a :stub repository; a repository that is not stored in the database.

The DEMAND argument specifies what kind of repository object the caller requires, at least. :tracked is greater than :known, which is greater than :stub. For example, if the caller requests a :known repository, a :tracked repository will do, while a :stub repository will not.

The valid values for DEMAND are:

- :tracked and :tracked? request a repository that the user added
  to the database. If there is no such repository, the former causes
  an error to be signaled, while for the latter nil is returned.

- :known? and :insert! request a repository from the database.
  Whether the user explicitly added it does not matter. If there is no
  such repository, nil is returned for the former, while for the latter
  a new repository is inserted into the repository and then returned.

- :stub and :stub? request the Forge repository corresponding to
  the current Git repository. It does not matter whether it is known.
  This fails if default-directory is not inside a Git repository, if
  there is no matching entry in forge-alist, or if it is unclear which
  remote to use. If the repository cannot be determined, the former
  causes an error to be signaled, while for the latter nil is returned.

  Stub repository objects are created without making an API request, so
  we lack access to the upstream ID, which the IDs used in out database,
  derive from. Stub repositories are "unknown" in the sense that their
  IDs are not :known. This is done to allow offline operations.

- :valid? requests the Forge repository corresponding to the current
  Git repository. It does not matter whether it is known. If it is
  unknown, an API request is made to verify that the repository exists
  on the forge. If it does, an object with a valid upstream ID is
  returned, but that isn't inserted into the database. If not, nil is
  returned.

Given a repository object, you can query its condition slot to learn whether it is :tracked, :known (i.e., has a valid ID and is stored in the database), or merely a :stub.

You can also use (forge-get repository OBJECT nil DEMAND) to check the condition of a repository object, or even to ensure a repository object has a valid upstream ID (using :valid?), or that it is tracked in the database (using :insert!).

Use forge-repository-equal to check if two objects refer to the same repository.

Also see info node (forge) Repository Detection.

Implementations

(forge-get-repository (NOTIFY forge-notification)) in `forge-notify.el'.

Return the object for the repository that NOTIFY belongs to.

(forge-get-repository (POST forge-pullreq-post)) in `forge-pullreq.el'.

Undocumented

(forge-get-repository (POST forge-issue-post)) in `forge-issue.el'.

Undocumented

(forge-get-repository (POST forge-discussion-reply)) in `forge-discussion.el'.

Undocumented

(forge-get-repository (POST forge-discussion-post)) in `forge-discussion.el'.

Undocumented

(forge-get-repository (TOPIC forge-topic)) in `forge-topic.el'.

Undocumented

(forge-get-repository (POST forge-post)) in `forge-post.el'.

Undocumented

(forge-get-repository (_ null) &optional NOERROR DEMAND) in `forge-repo.el'.

Undocumented

(forge-get-repository (REPO forge-repository) &optional NOERROR DEMAND) in `forge-repo.el'.

Undocumented

(forge-get-repository (ARG0 list) &rest REST) in `forge-repo.el'.

((HOST OWNER NAME) &optional REMOTE DEMAND)

Return the repository identified by HOST, OWNER and NAME. See `forge-alist' for valid Git hosts.

(forge-get-repository (URL string) &optional REMOTE DEMAND) in `forge-repo.el'.

Return the repository at URL.

(forge-get-repository (DEMAND symbol) &optional REMOTE NOTATPT) in `forge-repo.el'.

Return the current forge repository.

First check if `forge-buffer-repository', or if that is nil, then the repository for `forge-buffer-topic', satisfies DEMAND. If so, then return that repository.

Otherwise return the repository for `default-directory', if that exists and satisfies DEMAND. If that fails too, then return nil or signal an error, depending on DEMAND.

(forge-get-repository (_ (eql :dir)) DIR) in `forge-repo.el'.

Undocumented

(forge-get-repository (_ (eql :id)) ID) in `forge-repo.el'.

Undocumented

Source Code

;; Defined in ~/.emacs.d/elpa/forge-20260408.1922/forge-core.el
(cl-defgeneric forge-get-repository (demand)
  "Return a forge repository object or nil, or signal an error.

A forge repository is a repository hosted on a forge.  The local clone
is also a \"repository\", but it is a \"Git\" repository, not a \"Forge\"
repository.  (Forge repositories are also Git repositories, but not the
other way around.)

A `:known' repository has an entry in the local database.  All other
repositories are unknown.  `:known' repositories are divided into two
subgroups: `:tracked' and \"untracked\" repositories.

A `:tracked' repository was previously explicitly added to the database
by the user.

When Forge encounters a repository, without being instructed by the user
to track it, it may nevertheless add limited information about it to the
database.  Such a repository is `:known' but it is not `:tracked'.

Other repositories are \"unknown\".  Most commands can only deal with
repositories that are stored in the database.  Of these, some can deal
with any `:known' repositories, others require that they are `:tracked'.

Some other commands exist — such as the browse commands — that have no
such requirement.  While such commands also require a repository object,
they do not care whether that is stored in the database.  Instead they
are happy to use a `:stub' repository; a repository that is not stored
in the database.

The DEMAND argument specifies what kind of repository object the caller
requires, at least.  `:tracked' is greater than `:known', which is
greater than `:stub'.  For example, if the caller requests a `:known'
repository, a `:tracked' repository will do, while a `:stub' repository
will not.

The valid values for DEMAND are:

- `:tracked' and `:tracked?' request a repository that the user added
  to the database.  If there is no such repository, the former causes
  an error to be signaled, while for the latter nil is returned.

- `:known?' and `:insert!' request a repository from the database.
  Whether the user explicitly added it does not matter.  If there is no
  such repository, nil is returned for the former, while for the latter
  a new repository is inserted into the repository and then returned.

- `:stub' and `:stub?' request the Forge repository corresponding to
  the current Git repository.  It does not matter whether it is known.
  This fails if `default-directory' is not inside a Git repository, if
  there is no matching entry in `forge-alist', or if it is unclear which
  remote to use.  If the repository cannot be determined, the former
  causes an error to be signaled, while for the latter nil is returned.

  Stub repository objects are created without making an API request, so
  we lack access to the upstream ID, which the IDs used in out database,
  derive from.  Stub repositories are \"unknown\" in the sense that their
  IDs are not `:known'.  This is done to allow offline operations.

- `:valid?' requests the Forge repository corresponding to the current
  Git repository.  It does not matter whether it is known.  If it is
  unknown, an API request is made to verify that the repository exists
  on the forge.  If it does, an object with a valid upstream ID is
  returned, but that isn't inserted into the database.  If not, nil is
  returned.

Given a repository object, you can query its `condition' slot to learn
whether it is `:tracked', `:known' (i.e., has a valid ID and is stored
in the database), or merely a `:stub'.

You can also use (forge-get repository OBJECT nil DEMAND) to check the
condition of a repository object, or even to ensure a repository object
has a valid upstream ID (using `:valid?'), or that it is tracked in the
database (using `:insert!').

Use `forge-repository-equal' to check if two objects refer to the same
repository.

Also see info node `(forge) Repository Detection'.")