#+title: emacs-forgejo

Emacs front-end for [[https://forgejo.org][Forgejo]] instances (Codeberg, self-hosted, etc.).

+ Browse, filter, and view issues and pull requests
+ Submit and merge PRs via [[https://forgejo.org/docs/latest/user/agit-support/][AGit-Flow]] push options
+ Full code review workflow with threaded comments
+ Watch rules with per-repo filter polling and desktop notifications
+ Label, assignee, and milestone management
+ =SQLite= cache for instant display and offline usage
+ Multi-host support with per-instance token configuration
+ =#= and =@= completion in composition buffers (=gfm-mode=)
+ Repository settings editor

* Installation

** use-package
=emacs-forgejo= is available via [[https://elpa.gnu.org/packages/forgejo.html][GNU ELPA]].

#+begin_src emacs-lisp
  (use-package forgejo
    :ensure t
    :custom
    (forgejo-hosts '(("https://codeberg.org")))
    ;; Example watch rules
    (forgejo-watch-rules
     '(("thanosapollo/emacs-forgejo")
       ("guix/guix" . "state:open label:team-emacs")
       ("*" . "author:<your username>")))
    (forgejo-watch-filter-default "read:no"))
#+end_src

Visit a codeberg/forgejo repo and call =M-x forgejo-vc=.  It will
automatically handle the token creation.

* Usage

From any git repository with a Forgejo remote, =C-x v f=
(=forgejo-vc=) opens the Forgejo popup menu.  All available
commands are listed there.  Press =h= in any view to see keybindings.

=M-x forgejo= opens the top-level menu for repo search, issue/PR
browsing, and watch list.

** Watch rules

Poll specific repos for new issues/PRs on a timer:

#+begin_src emacs-lisp
  (setq forgejo-watch-rules
        '("thanosapollo/emacs-forgejo" ;; all for thanosapollo/emacs-forgejo repo
          ("guix/guix" . "state:open label:team-emacs") ;; all state:open with team-emacs label
          ("*" . "author:<your-username>"))) ;; everything in the db with author:<your-username>
  (forgejo-watch-mode 1)
#+end_src

A bare string watches everything in that repo.  A cons cell applies a
filter query.  =*= expands to all repos in your local cache.

=M-x forgejo-watch-list= to browse watched items.  The initial filter
is controlled by =forgejo-watch-filter-default=:

#+begin_src emacs-lisp
  (setq forgejo-watch-filter-default "read:no")
#+end_src

Supported prefixes: =state:=, =read:=, =type:=, =author:=, =label:=, =search:=.

** Composition

Composition buffers use =gfm-mode= for markdown highlighting with =#=
completion for issue/PR references and =@= for user mentions.

#+begin_src emacs-lisp
  (add-hook 'forgejo-compose-hook #'flyspell-mode)
#+end_src

** Buffer setup

All Forgejo buffers call =forgejo-buffer-setup-functions= after
setup, passing the buffer as an argument:

#+begin_src emacs-lisp
  (setq forgejo-buffer-setup-functions
        (list (lambda (buf)
                (with-current-buffer buf
                  (display-line-numbers-mode -1)))))
#+end_src

** Bug reference integration

=forgejo-browse-mode= intercepts Forgejo URLs and opens them in
forgejo.el instead of the browser.  Hook it into =bug-reference-mode=
so that =#N= references in source files, ERC, and vc/magit buffers open
directly in forgejo.el:

#+begin_src emacs-lisp
  (add-hook 'bug-reference-mode-hook #'forgejo-browse-mode)
  (add-hook 'bug-reference-prog-mode-hook #'forgejo-browse-mode)
#+end_src

Enable =bug-reference-mode= in buffers where you want =#N= references
(see [[info:emacs#Bug Reference][Bug Reference]]):

#+begin_src emacs-lisp
  (add-hook 'prog-mode-hook #'bug-reference-prog-mode)
  (add-hook 'log-view-mode-hook #'bug-reference-mode)
  (add-hook 'vc-annotate-mode-hook #'bug-reference-mode)
  (add-hook 'magit-revision-mode-hook #'bug-reference-mode)
#+end_src

You can also toggle it per-buffer with =M-x forgejo-browse-mode=.

For ERC/rcirc, configure =#N= references per channel:

#+begin_src emacs-lisp
  (add-to-list 'bug-reference-setup-from-irc-alist
               '("#guix" "Libera.Chat"
                 "\\(#\\([0-9]+\\)\\)\\>"
                 "https://codeberg.org/guix/guix/issues/%s"))
#+end_src

* Contributing
This project is part of GNU ELPA.

Contributions of ~15 lines or more require [[https://www.gnu.org/prep/maintain/html_node/Copyright-Papers.html][FSF copyright assignment]].

#+BEGIN_QUOTE
See [[https://codeberg.org/thanosapollo/emacs-forgejo/issues/17][#17]] for more.
#+END_QUOTE

* Screenshots

#+caption: issue list
[[https://thanosapollo.org/images/emacs-forgejo--issue-01.png]]

#+caption: issue view
[[https://thanosapollo.org/images/emacs-forgejo--issue.png]]

#+caption: review comment
[[https://thanosapollo.org/images/emacs-forgejo--review-comment.png]]

#+caption: review log
[[https://thanosapollo.org/images/emacs-forgejo--review-log.png]]

#+caption: review thread
[[https://thanosapollo.org/images/emacs-forgejo--review-thread.png]]
