Is an explanation of the basic operation principle of Forge missing from the docs?

[grothesque]

I recently started using Forge. For me, a heavy user of Magit and many other Emacs packages, the biggest initial hurdle to wrapping my head around Forge was understanding its basic operating principle. Most Emacs packages that deal with “objects” of some kind (say Magit, or org-mode, or AucTeX, or project.el), associate object identity with a file system path and default-directory of the mode-specific buffers matches the directory of the “object”.

Forge is very different in this regard: the primary identity of an “object” in Forge (i.e. a repository) is the repository as hosted on a forge, such as github.com/owner/project, not a local checkout path. A Git remote in a local clone is one way Forge discovers that hosted repository, but the Forge repository itself is not identified by that local remote or by the clone’s path.

This distinction is not academic, because the Forge database is more than a cache. It potentially stores a lot of local and private data (like notes, marks, choice of topics, etc.)

If other Forge users are like me, explaining the above ideas prominently and early in the documentation would help. (The information is mostly already there, but it is spread across the docs, and partially implicit.)

[grothesque]

For reference, here is what I’ve put into my own notes. (I’m not saying that this is appropriate for Forge documentation, just trying to show what aspects I find worth explaining better.)

---

Overview

Forge differs from Emacs packages like Magit, project.el, and AUCTeX: its first-class objects are remote repositories, not local file system paths. Forge “knows” about a set of remote repositories that can be listed with M-x forge-list-repositories. Forge adds a remote repository to its known/tracked set upon explicit request, typically `N f f` from Magit.

A repository may be optionally associated with a local git worktree, but this is not exclusive. It is possible to use the same forge repository with multiple worktrees. The last used worktree will be remembered as the associated one.

Mapping from cwd to a Forge repository is supported [according to fixed rules](info:forge#How Forge Detection Works). In short, if there is only one remote Forge uses it; otherwise it tries forge.remote, then upstream, then origin.

Forge stores its state in a central database (~/.emacs.d/forge-database.sqlite). The database is largely cache-like, but not entirely. At least the following information cannot be re-fetched if the database is deleted:

• choice of repositories, individual topics (in selective workflow),
• choice of selective mode, or not having fetched topics before some date,
• associated worktree path,
• private per-topic status (unread, pending, done), topic marks (and mark definitions), notes

[tarsius]

Thanks! I've added this mostly unchanged, see 12f0ea0.