#+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

#+BEGIN_QUOTE
Requires Emacs 29.1+ (native JSON, native SQLite), =markdown-mode=, and
[[https://codeberg.org/thanosapollo/emacs-keymap-popup][keymap-popup]].
#+END_QUOTE

* Installation

** use-package (Emacs 30+, recommended)

Install =keymap-popup= first:

#+begin_src emacs-lisp
  (use-package keymap-popup
    :vc (:url "https://codeberg.org/thanosapollo/emacs-keymap-popup"
            :branch "master"
            :rev :newest))
#+end_src

Then install =forgejo=:

#+begin_src emacs-lisp
  (use-package forgejo-vc
    :vc (:url "https://codeberg.org/thanosapollo/emacs-forgejo"
	    :branch "master"
            :rev :newest
            :lisp-dir "lisp")
    :custom
    (forgejo-hosts '(("https://codeberg.org")))
    (forgejo-watch-rules '(("thanosapollo/emacs-forgejo")
                           ("guix/guix" . "state:open label:team-emacs")
                           ("*" . "author:<your username>")))
    (forgejo-watch-filter-default "read:no"))
#+end_src

Store your token in =~/.authinfo.gpg=:

#+begin_example
machine codeberg.org login YOUR_USERNAME password YOUR_TOKEN
#+end_example

Or provide tokens inline:

#+begin_src emacs-lisp
  (setq forgejo-hosts '(("https://codeberg.org" "your-token")
                         ("https://git.myorg.com" "other-token")))
#+end_src

** Manual

Clone [[https://codeberg.org/thanosapollo/emacs-keymap-popup][keymap-popup]] and add both to your load path:

#+begin_src emacs-lisp
  (add-to-list 'load-path "/path/to/emacs-keymap-popup")
  (add-to-list 'load-path "/path/to/emacs-forgejo/lisp")
  (require 'forgejo-vc)
#+end_src

** Guix

#+begin_src sh
  guix package -f guix.scm
#+end_src

* 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/forgejo.el"
          ("guix/guix" . "state:open label:team-emacs")
          ("*" . "author:thanosapollo")))
  (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

* 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]]
