src/Repositories.hs Modified

@@ -12,9 +12,10 @@
 import Conduit (runConduit, sinkList, (.|))
 import Control.Exception (try)
 import Control.Monad (filterM, unless, when, (<=<))
+import Control.Monad.Extra (ifM)
 import Control.Monad.IO.Class (liftIO)
 import Control.Monad.Trans.Reader (ReaderT)
-import Data.Either (fromRight, isRight)
+import Data.Either (isRight)
 import qualified Data.HashMap.Strict as HashMap
 import Data.Maybe (catMaybes, fromJust, mapMaybe)
 import Data.Tagged
@@ -25,8 +26,8 @@
 import Git.Libgit2 (LgRepo, lgFactory)
 import Path (Abs, Dir, File, Path, Rel, dirname, parseRelDir, parseRelFile, toFilePath, (</>))
 import Path.IO (doesFileExist, ensureDir)
+import qualified System.Directory as D
 import qualified System.FilePath as FP
-import System.IO.Error (tryIOError)
 import Text.Ginger.GVal (GVal, ToGVal, toGVal)
 
 import Templates (Env (..), Template (..), generate)
@@ -54,10 +55,31 @@
     okRepo p = try . liftIO . openRepository lgFactory $ defaultRepositoryOptions{repoPath = toFilePath p}
 
 {-
-Pass the repository's folder, get its description.
+Pass the repository's folder, get its description. The algorithm is:
+
+    1. Check for a description in repo/description
+    2. Check for a description in repo/.git/description
+    3. Fallback to the repo folder's name.
+
 -}
 getDescription :: Path Abs Dir -> IO Text
-getDescription = fmap (fromRight "") . tryIOError . fmap (strip . pack) . readFile . flip FP.combine "description" . toFilePath
+getDescription dir =
+    ifM
+        (D.doesFileExist inTop)
+        (return . Just $ inTop)
+        ( ifM
+            (D.doesFileExist inGit)
+            (return . Just $ inGit)
+            (return Nothing)
+        )
+        >>= \case
+            Just file ->
+                strip . pack <$> readFile file
+            Nothing ->
+                return . pack . toFilePath . dirname $ dir
+  where
+    inTop = toFilePath dir FP.</> "description"
+    inGit = toFilePath dir FP.</> ".git" FP.</> "description"
 
 {-
 This receives a file path to a single repository and tries to process it. If the

DOCUMENTATION.md Modified

@@ -140,7 +140,7 @@
 |        | repositories | A list of all of the git repositories.                |
 | Repo   |              | *In addition to the variables from the index scope...*|
 |        | name         | The repository name, taken from its folder name.      |
-|        | description  | A description taken from a file called "description" in that folder.|
+|        | description  | The repository's description (see below).             |
 |        | commits      | A list of the repository's commits.                   |
 |        | tree         | A list of the repository's files.                     |
 |        | tags         | A list of the refs corresponding to tags.             |
@@ -163,7 +163,7 @@
 | Object     | Attribute        | Description                                              |
 | ---------- | ---------------- | -------------------------------------------------------- |
 | repository | name             | The repository's name, taken from the folder name.       |
-|            | description      | A description taken from a file called "description" in that folder.|
+|            | description      | The repository's description (see below).                |
 |            | head             | The current git commit.                                  |
 |            | updated          | The time when the current commit was committed.          |
 | commit     | id               | The SHA of the given commit.                             |
@@ -197,6 +197,15 @@
   `branches[0].commit.parent` will work as expected.
 - "file" includes directories and symbolic links.
 
+#### Descriptions
+
+Each repository can have a description that is available in the templates. This
+is how the description for a given respository is determined:
+
+1. Look for a file at `repo/description`, and if found read from there.
+2. Otherwise, look for a file at `repo/.git/description`, and if found read from there.
+2. Otherwise, simply use the repository folder's name.
+
 Questions?
 ----------