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.

diff --git a/docs/git.md b/docs/git.md
index 1a8834dfc876bd8a68d7a661a38646ccd50bfbb7..3957f4743929a0d51ae602fbe5903ed89b18e808 100644 (file)
--- 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 a458ccf020dfa34dc500fcf3d4c66bc1f2fd55f3..ffaf91bd8e3b2ef43b02b3b344f1914f40ff0548 100644 (file)
--- 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"