Contributing to Git Projects with Magit: PRs, Patches & Agit workflow

Quick video guide on contributing to git projects using Magit. Showing an overview of the 3 most commonly used workflows

  • Pull Requests
  • Agit Workflow
  • Git patches

Video notes:

Introduction

I’m creating this as a tutorial video on how to contribute to bebliotheca, a digital recreation of the Library of Constantinople to host texts that would have been found there during the Greco-Roman Empire.

The steps demonstrated here are applicable to any project.

This is a video guide on contributing to git projects, using Emacs and Magit (the magical Git client). Magit provides the best experience out of the box for a text based interface to git, which makes magit an emacs’ killer feature.

In this video we will start from an example Emacs configuration, adding a theme and installing Magit. Afterwards we will see how to contribute to git projects in 3 ways:

I personally use vc, a built-in module. But that’s because I enjoy tinkering and writing my own scripts for it. Magit does by default a lot more that even my ~300 line vc config can do.

Requirements

You will need the following software installed:

Additionally, ensure you have a pair of SSH keys already generated and set up for your forge.

Emacs Configuration I will be using

Example init.el file that I will be using:

  • Defaults locations for init.el, depending on your system:
    • GNU/Linux: ~/.emacs.d/init.el
    • Windows: C:\Users\<YourUsername>\.emacs.d\init.el

;; Init packages
(package-initialize)

;;;; Do not install keycast as well, I'm only using it to share my
;;;; keystrokes for the video.
;; (use-package keycast
;;  :ensure t)



;; Set and load custom.el
(setf custom-file (locate-user-emacs-file "custom.el"))
(load custom-file 'noerror)

;; Completions
(fido-vertical-mode 1)
(electric-pair-mode 1)

;;; Theming ;;;

(column-number-mode)
(global-display-line-numbers-mode 1)
(tool-bar-mode -1)
(tooltip-mode -1)
(menu-bar-mode -1)
(blink-cursor-mode -1)
(scroll-bar-mode -1)
(set-fringe-mode -1)

;; Add transparency
(add-to-list 'default-frame-alist '(alpha-background . 85))

;; ef-themes package provides a great theme collection, made by Protesilaos.
(use-package ef-themes
  :ensure t)

(defun thanos/load-theme (&optional theme)
  "Disable current theme and load a new THEME.
Emacs can load multiple themes at once.  With this function we make sure we only load one at a time"
  (interactive)
  (let ((theme (or theme (intern (completing-read "Theme: " (custom-available-themes))))))
    (disable-theme (car custom-enabled-themes))
    (load-theme theme t)))

(thanos/load-theme 'ef-dark)


(use-package magit
  :bind ("C-x g" . magit)
  ;; Hook flyspell for autocorrect during commit messages.
  :hook (git-commit-mode . flyspell-mode))

;; Agitjo extends Magit with a new menu for AGit-Flow operations.
(use-package agitjo
  :vc (:url "https://codeberg.org/halvin/agitjo")
  :ensure t)

Pull Requests

  • Require an account creation for the forge the project is hosted at. e.g Github or Codeberg.
  • Steps to submit a PR
    • Fork repository, through a Web UI.
    • Clone your fork
    • Commit changes, often in a new branch.
    • Push your changes to your fork
    • Submit a Pull Request, through a Web UI.

If you’d rather not use a Web UI, but have to use Pull Requests, consider using forge.

Agit workflow

Note that the agit workflow is not supported by GitHub at the time of making this video. To use agit workflow, you will need to utilize a forgejo instance such as Codeberg.

  • Clone repo, using ssh
  • Commit changes
  • Push
    • From the Magit status buffer, press #
    • Specify a title using -t
      • You can use the same title to push changes to the PR.

Git patches

  • Clone repo.
  • Commit changes.
  • Format patches.
$ git format-patch -{NUM} # where NUM the number of commits.
  • Send patches as attachments via email, by pressing C-x C-m.