Org-Mode, Git Logs, and Org-Babel for Running Reports

Feeding the Personal Knowledge Management System

In Using a File as a Template in Emacs, I wrote about the end of week reports that my supervisor tasked me with writing. I want to expand a bit on one of the scripts I uses to help me fill out that report.

The Script

The following script is one of the tools I use to help me write my end of week report. It only considers the Forem code base.

cd ~/git/forem ;
echo "Authored PRs Merged Since 2022-03-25\n"
git log --since=2022-03-25 \
  --format="%h — %s %an, (%cs) %d" \
  --author="(Suzanne A|Jeremy F|Arit A|Dwight S|Anna B)"\
  | rg "— ([^\(]+) \(\#(\d+)\) ([^,]+)," --only-matching -r '- $1 :: forem/forem#$2 $1' \
  | sort
echo "\nCo-authored PRs Merged Since 2022-03-25\n"
git log --since=2022-03-25 \
  --grep="Co-authored-by: (Suzanne A|Jeremy F|Arit A|Dwight S|Anna B)" \
  --format="%(trailers:key=Co-authored-by,separator=%x2C,valueonly=true) :: %s" \
  | rg "^([^<]+) <.*> :: ([^\(]+) \(\#(\d+)\)" --only-matching -r '- $1 :: forem/forem#$3 $2' \
  | sort

In the above script there are two sections:

• The first section are the commits authored by members of the Content Experience Pod.
• The second section are the commits in which pod members contributed one or more commits to the PR but were not the initiating author; Git registers these as Co-authors.

In other words, the script shows what code my team helped ship for the week.

Where to File Away that Script?

For a week or two I was running a simpler version of the above script; I would search through my shell command history, find the one that looked right, and adjust the date.

That worked but I’d prefer to not rely on that workflow. I added the script to my Content Experience Pod’s Org-Roam node; a document that is part of my PKM system.

Here’s what it looks like in that document:

#+Begin_src sh :results output :cmdline (org-read-date)
  cd ~/git/forem ;
  echo "Authored PRs Merged Since $1\n"
  git log --since=$1 \
    --format="%h — %s %an, (%cs) %d" \
    --author="(Suzanne A|Jeremy F|Arit A|Dwight S|Anna B)"\
    | rg "— ([^\(]+) \(\#(\d+)\) ([^,]+)," --only-matching -r '- $3 :: forem/forem#$2 $1' \
    | sort
  echo "\nCo-authored PRs Merged Since $1\n"
  git log --since=$1 \
    --grep="Co-authored-by: (Suzanne A|Jeremy F|Arit A|Dwight S|Anna B)" \
    --format="%(trailers:key=Co-authored-by,separator=%x2C,valueonly=true) :: %s" \
    | rg "^([^<]+) <.*> :: ([^\(]+) \(\#(\d+)\)" --only-matching -r '- $1 :: forem/forem#$3 $2' \
    | sort
#+end_src

It’s a little different, because I’ve written it using Org-Mode’s Babel syntax.

The first line (e.g. #+Begin_src sh :results output :cmdline (org-read-date)) declares:

• A code-block with sh syntax
• To write results as raw output
• To pass the results of the (org-read-date) function as $1 to the script

The remaining lines are almost verbatim of what I previously wrote; except instead of the “hard-coded” date of 2022-03-25 I’m using the results of the org-read-date function.

To run the report, I set point (e.g. the cursor) in that code block, type C-c C-c and Emacs evaluates the Babel block.

First it calls the org-read-date function, prompting me to select a date. Then it runs the shell command. And outputs the results just below the Babel block.

From there, I can see one aspect of the work my team has done for the week.

Conclusion

Prior to adopting Emacs, and Org-Mode specifically, I would’ve floundered on where to put this. It would’ve remained in my shell history.

But now that I’ve associated this with a group of people, written it in a less ephemeral file, and written about it, I will be more likely to remember both it’s existence and what it did.

I learned about Git’s commit trailers and how to find the Co-authors of a commit. Which helps make visible the work that folks do to help another person get their pull request merged.

I also learned a bit more about passing arguments from Babel into the script it’s executing.

And last, because I wrote this blog post in my PKM system, I have a reference from the published blog post, to the Content Experience Pod.

In other words, I’m doing my best to create breadcrumbs to help me find the particulars of a script I wrote.