From a70b4136bfcb33409343ac420672ed3be233dbb6 Mon Sep 17 00:00:00 2001
From: Matthias Kruk <m@m10k.eu>
Date: Wed, 12 Apr 2023 10:57:26 +0900
Subject: [PATCH] include/git: Add function for listing commits in a branch

When working with the history of git repositories, it would be
helpful to have a function that can be used to query the commits
in a branch.

This commit adds the git_branch_get_commits() function, which lists
the commit hash, date, and committer email address for each commit
of a branch.
---
 docs/git.md    | 39 +++++++++++++++++++++++++++++++++++++++
 include/git.sh | 11 +++++++++++
 2 files changed, 50 insertions(+)

diff --git a/docs/git.md b/docs/git.md
index 1a8834d..3957f47 100644
--- a/docs/git.md
+++ b/docs/git.md
@@ -15,6 +15,7 @@ repositories in the local file system.
 | [git_commit()](#git_commit)                         | Commit a change to the current branch |
 | [git_branch_new()](#git_branch_new)                 | Create a new branch                   |
 | [git_branch_get_current()](#git_branch_get_current) | Get the name of the current branch    |
+| [git_branch_get_commits()](#git_branch_get_commits) | List the commits in a branch |
 | [git_branch_checkout()](#git_branch_checkout)       | Change the current branch             |
 | [git_merge()](#git_merge)                           | Merge one branch into another one     |
 | [git_push()](#git_push)                             | Push a branch to a remote             |
@@ -163,6 +164,44 @@ no data is written to standard output.
 
 In case of an error, `git_branch_get_current()` will write an error message to standard error.
 
+## git_branch_get_commits()
+
+List the commits in a branch
+
+### Synopsis
+
+    git_branch_get_commits "$repository" "$branch"
+
+### Description
+
+The `git_branch_get_commits()` function lists the commits in the branch `branch` of the
+repository identified by `repository`. For each commit in the branch, it will write one
+line containing the commit hash, date, and email address of the committer to standard
+output.
+Commits are listed in reverse chronological order starting with the newest commit.
+
+### Return value
+
+| Return value | Meaning                             |
+|--------------|-------------------------------------|
+| 0            | Success                             |
+| 1            | Could not lookup the branch history |
+
+### Standard input
+
+This function does not read from standard input.
+
+### Standard output
+
+On success, all commits that are part of the branch will be written to standard output, one
+commit per line. Each line contains the commit hash, date, and committer email address,
+separated by single-width space characters. The date is output in strict ISO 8601 format.
+Commits are output in reverse chronological order starting with the newest commit.
+
+### Standard error
+
+This function does not write to standard error.
+
 
 ## git_branch_checkout()
 
diff --git a/include/git.sh b/include/git.sh
index a458ccf..ffaf91b 100644
--- a/include/git.sh
+++ b/include/git.sh
@@ -65,6 +65,17 @@ git_branch_get_current() {
 	return 0
 }
 
+git_branch_get_commits() {
+	local repository="$1"
+	local branch="$2"
+
+	if ! (cd "$repository" && git log --format="%H %aI %ae" "$branch" 2>/dev/null); then
+		return 1
+	fi
+
+	return 0
+}
+
 git_branch_checkout() {
 	local repository="$1"
 	local branch="$2"
-- 
2.47.3