#+title: magit-standup
#+author: István Karaszi

[[https://melpa.org/#/magit-standup][file:https://melpa.org/packages/magit-standup-badge.svg]]

Collect recent git commits across multiple repositories and format them as org-mode standup notes.

[[file:screenshots/standup-buffer.png]]

* Features

- Scans one or more git repositories for your recent commits
- Weekday-aware lookback: on Monday (and weekends) looks back to Friday; otherwise looks back 1 day
- Transient menu lets you override the since-date, the repository list and the author list before running
- Filters by several authors at once, which helps when you commit under more than one identity
- Output is an org-mode buffer with clickable commit links (via [[https://github.com/magit/orgit][orgit]] or [[https://orgmode.org/worg/org-contrib/org-git-link.html][org-git-link]])
- Directories that aren't git repos are searched recursively for nested repos

* Requirements

- Emacs 28.1+
- [[https://github.com/magit/magit][Magit]] 4.5.0+
- [[https://github.com/magit/transient][Transient]] 0.8.0+

* Installation

** From MELPA

The package is on [[https://melpa.org/#/magit-standup][MELPA]]. If you do not
have MELPA in =package-archives=, add it first:

#+begin_src emacs-lisp
(require 'package)
(add-to-list 'package-archives
             '("melpa" . "https://melpa.org/packages/") t)
#+end_src

Then install the package:

#+begin_example
M-x package-refresh-contents RET
M-x package-install RET magit-standup RET
#+end_example

** With use-package

#+begin_src emacs-lisp
(use-package magit-standup
  :ensure t
  :custom
  (magit-standup-repos '("~/Projects"))
  (magit-standup-authors '("you@example.com")))
#+end_src

** With Doom Emacs

Add the package to =~/.config/doom/packages.el=:

#+begin_src emacs-lisp
(package! magit-standup)
#+end_src

Configure the package in =~/.config/doom/config.el=:

#+begin_src emacs-lisp
(use-package! magit-standup
  :defer t
  :config
  (setq magit-standup-repos '("~/Projects")
        magit-standup-authors '("you@example.com")))
#+end_src

Run =doom sync= and restart Emacs.

** With straight.el

#+begin_src emacs-lisp
(straight-use-package 'magit-standup)
#+end_src

** Manual

Clone the repository and add it to your =load-path=:

#+begin_src emacs-lisp
(add-to-list 'load-path "/path/to/magit-standup")
(require 'magit-standup)
#+end_src

* Usage

Run =M-x magit-standup= to open the transient menu:

- =-d= / =--since== — override the since-date (defaults to the weekday-aware computed date)
- =-r= / =--repos== — override the repository list
- =-a= / =--authors== — override the author list (comma-separated)
- =s= — show the standup buffer

Press =s= to generate the standup notes in a =*magit-standup*= buffer.

* Configuration

All options can be customized via =M-x customize-group RET magit-standup=.

| Variable                        | Default | Description                                                        |
|---------------------------------+---------+--------------------------------------------------------------------|
| =magit-standup-repos=           | =nil=   | List of directories to scan. When nil, uses current repo.          |
| =magit-standup-repos-max-depth= | =1=     | Max depth to search non-repo directories for nested repos.         |
| =magit-standup-authors=         | =nil=   | List of author filters. When nil, uses =git config user.email=.    |
| =magit-standup-since-days-ago=  | =nil=   | Fixed lookback override. When nil, weekday-aware logic.            |
| =magit-standup-link-package=    | =nil=   | Link style: =orgit=, =org-git-link=, =none=, or nil (auto-detect). |

** Authors

Git keeps a commit when it matches one of the entries in
=magit-standup-authors=. Give every identity you commit under:

#+begin_src emacs-lisp
(setq magit-standup-authors (list "you@example.com"
                                  "you@work.example.com"))
#+end_src

Git applies =.mailmap= to the author filter. If a repository maps your
commit email to another identity, give the mapped identity here. If you
get no commits, compare these two commands:

#+begin_src shell
git log --author=you@example.com --all
git log --format='%aN <%aE>' -1
#+end_src

The variable =magit-standup-author= (singular) still works, but it is
obsolete since version 0.2.0. Use =magit-standup-authors= instead.

* Development

The project uses [[https://devenv.sh/][devenv]]. It gives you Emacs and
[[https://emacs-eask.github.io/][Eask]].

#+begin_src shell
devenv shell     # open a shell with the tools
devenv test      # compile, lint and test
#+end_src

With [[https://direnv.net/][direnv]], run =direnv allow= once. The tools then
load when you enter the directory.

* Release

To make a release, run:

#+begin_src shell
make release VERSION=0.3.0
#+end_src

The target runs the linter and the tests. Then it creates the branch
=release/v0.3.0= and commits the new version. Push the branch and open
a pull request:

#+begin_src shell
git push -u origin release/v0.3.0
gh pr create --fill --label release
#+end_src

When you merge the pull request, a workflow creates the tag and
publishes the release with the generated notes.

* License

GPL-3.0-or-later