From 4b23ebdfdc12bcef58d9b65e81884e4d3d9d5f5d Mon Sep 17 00:00:00 2001
From: Uwe Hubert <hubert@doctronic.de>
Date: Mon, 15 Jan 2018 17:48:17 +0100
Subject: [PATCH] Added the placeholder {git-commit-id} for the :source-uri.

This is replaced with the Git commit id of the repository.
Eg:
:codox
 {:source-uri
  "http://gerrit.mydomain.de/gitlist/myproject.git/blob/{git-commit-id}/{filepath}#L{line}"}

Will result in:
 http://gerrit.mydomain.de/gitlist/myproject.git/blob/17073c0db441f5550a6cdbd1e5d2143ae6f5b576/src/de/mydomain/foo/bar.clj#L23

See
https://github.com/weavejester/codox/issues/168
---
 README.md                       | 11 ++++----
 codox/src/codox/main.clj        | 48 +++++++++++++++++++++++++--------
 codox/src/codox/writer/html.clj | 13 ++++-----
 example/project.clj             |  2 +-
 4 files changed, 51 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 8caf08c..3b38444 100644
--- a/README.md
+++ b/README.md
@@ -211,11 +211,12 @@ to the function's source file in the documentation, you can set the
 
 The URI is a template that may contain the following keys:
 
-* `{filepath}`  - the file path from the root of the repository
-* `{basename}`  - the basename of the file
-* `{classpath}` - the relative path of the file within the source directory
-* `{line}`      - the line number of the source file
-* `{version}`   - the version of the project
+* `{filepath}`      - the file path from the root of the repository
+* `{basename}`      - the basename of the file
+* `{classpath}`     - the relative path of the file within the source directory
+* `{line}`          - the line number of the source file
+* `{version}`       - the version of the project
+* `{git-commit-id}` - the Git commit id of the repository
 
 You can also assign different URI templates to different paths of your
 source tree. This is particularly useful for created source links from
diff --git a/codox/src/codox/main.clj b/codox/src/codox/main.clj
index ae884af..de56d0b 100644
--- a/codox/src/codox/main.clj
+++ b/codox/src/codox/main.clj
@@ -1,7 +1,9 @@
 (ns codox.main
   "Main namespace for generating documentation"
   (:use [codox.utils :only (add-source-paths)])
-  (:require [codox.reader.clojure :as clj]
+  (:require [clojure.string :as str]
+            [clojure.java.shell :as shell]
+            [codox.reader.clojure :as clj]
             [codox.reader.plaintext :as text]))
 
 (defn- writer [{:keys [writer]}]
@@ -91,17 +93,41 @@
                                (apply text/read-documents)
                                (sort-by :name))))
 
+(defn- git-commit-id [dir]
+  (let [res  (try
+               (shell/sh "git" "rev-parse" "HEAD"
+                         :dir dir)
+               (catch Throwable t
+                 {:exit -1
+                  :err  (.getMessage t)}))
+        exit (:exit res)
+        err  (:err res)
+        err  (if-not (str/blank? err)
+               err
+               (when-not (zero? exit)
+                 (str "exit code " exit)))
+        out  (if err
+               ""
+               (-> res :out (str/trim)))]
+    (if err
+      (println "Warning: error while calling Git:" err)
+      (when (str/blank? out)
+        (println "Warning: retrieved empty Git commit id.")))
+    out))
+
 (def defaults
-  {:language     :clojure
-   :root-path    (System/getProperty "user.dir")
-   :output-path  "target/doc"
-   :source-paths ["src"]
-   :doc-paths    ["doc"]
-   :doc-files    :all
-   :namespaces   :all
-   :exclude-vars #"^(map)?->\p{Upper}"
-   :metadata     {}
-   :themes       [:default]})
+  (let [root-path (System/getProperty "user.dir")]
+    {:language      :clojure
+     :root-path     root-path
+     :output-path   "target/doc"
+     :source-paths  ["src"]
+     :doc-paths     ["doc"]
+     :doc-files     :all
+     :namespaces    :all
+     :exclude-vars  #"^(map)?->\p{Upper}"
+     :metadata      {}
+     :themes        [:default]
+     :git-commit-id (git-commit-id root-path)}))
 
 (defn generate-docs
   "Generate documentation from source files."
diff --git a/codox/src/codox/writer/html.clj b/codox/src/codox/writer/html.clj
index 1c13bbd..306fb9a 100644
--- a/codox/src/codox/writer/html.clj
+++ b/codox/src/codox/writer/html.clj
@@ -151,16 +151,17 @@
   (second (re-find #"/([^/]+?)$" path)))
 
 (defn- var-source-uri
-  [{:keys [source-uri version]}
+  [{:keys [source-uri version git-commit-id]}
    {:keys [path file line]}]
   (let [path (util/uri-path path)
         uri  (if (map? source-uri) (get-source-uri source-uri path) source-uri)]
     (-> uri
-        (str/replace "{filepath}"  path)
-        (str/replace "{classpath}" (util/uri-path file))
-        (str/replace "{basename}"  (uri-basename path))
-        (str/replace "{line}"      (str line))
-        (str/replace "{version}"   version))))
+        (str/replace "{filepath}"      path)
+        (str/replace "{classpath}"     (util/uri-path file))
+        (str/replace "{basename}"      (uri-basename path))
+        (str/replace "{line}"          (str line))
+        (str/replace "{version}"       version)
+        (str/replace "{git-commit-id}" git-commit-id))))
 
 (defn- split-ns [namespace]
   (str/split (str namespace) #"\."))
diff --git a/example/project.clj b/example/project.clj
index 73c5b01..3b18028 100644
--- a/example/project.clj
+++ b/example/project.clj
@@ -14,7 +14,7 @@
    :doc-files ["doc/intro.md"
                "doc/formatting.md"]
    :source-uri
-   "https://github.com/weavejester/codox/blob/{version}/codox.example/{filepath}#L{basename}-{line}"
+   "https://github.com/weavejester/codox/blob/{git-commit-id}/example/{filepath}#L{basename}-{line}"
    :html
    {:transforms [[:head] [:prepend [:script "console.log('hello');"]]
                  [:head] [:append  [:script "console.log('world');"]]