githash-0.1.7.0: Compile git revision info into Haskell projects

Copyright | (c) 2018 Michael Snoyman 2015 Adam C. Foltzer
License | BSD3
Maintainer | michael@snoyman.com
Stability | provisional
Portability | portable
Safe Haskell | None
Language | Haskell2010

GitHash

Contents

- Types
  - Getters
- Creators
- Template Haskell

Description

Some handy Template Haskell splices for including the current git hash and branch in the code of your project. Useful for including in panic messages, `--version` output, or diagnostic info for more informative bug reports.

    {-# LANGUAGE TemplateHaskell #-}
    import GitHash

    panic :: String -> a
    panic msg = error panicMsg
      where panicMsg =
              concat [ "[panic ", giBranch gi, "@", giHash gi
                     , " (", giCommitDate gi, ")"
                     , " (", show (giCommitCount gi), " commits in HEAD)"
                     , dirty, "] ", msg ]
            dirty | giDirty gi = " (uncommitted files present)"
                  | otherwise   = ""
            gi = $$tGitInfoCwd

    main = panic "oh no!"

    % stack runghc Example.hs
    Example.hs: [panic master@2ae047ba5e4a6f0f3e705a43615363ac006099c1 (Mon Jan 11 11:50:59 2016 -0800) (14 commits in HEAD) (uncommitted files present)] oh no!

WARNING: None of this will work in a git repository without any commits.

Since: 0.1.0.0

Synopsis

- data GitInfo
- data GitHashException
  - = GHECouldn'tReadFile !FilePath !IOException
  - | GHEInvalidCommitCount !FilePath !String
  - | GHEInvalidGitFile !String
  - | GHEGitRunFailed !FilePath ![String] !ExitCode !String !String
  - | GHEGitRunException !FilePath ![String] !IOException
- giHash :: GitInfo -> String
- giBranch :: GitInfo -> String
- giDirty :: GitInfo -> Bool
- giCommitDate :: GitInfo -> String
- giCommitCount :: GitInfo -> Int
- giCommitMessage :: GitInfo -> String
- giDescribe :: GitInfo -> String
- giTag :: GitInfo -> String
- giFiles :: GitInfo -> [FilePath]
- getGitInfo :: FilePath -> IO (Either GitHashException GitInfo)
- getGitRoot :: FilePath -> IO (Either GitHashException FilePath)
- tGitInfo :: FilePath -> SpliceQ GitInfo
- tGitInfoCwd :: SpliceQ GitInfo
- tGitInfoTry :: FilePath -> SpliceQ (Either String GitInfo)
- tGitInfoCwdTry :: SpliceQ (Either String GitInfo)

# Types

data GitInfo Source #

Various pieces of information about a Git repository.

Since: 0.1.0.0

#### Instances

Instances details

Show GitInfo Source # |
Instance details Defined in GitHash Methods showsPrec :: Int -> GitInfo -> ShowS Source # show :: GitInfo -> String Source # showList :: [GitInfo] -> ShowS Source #
Lift GitInfo Source # |
Instance details Defined in GitHash Methods lift :: Quote m => GitInfo -> m Exp Source # liftTyped :: forall (m :: Type -> Type). Quote m => GitInfo -> Code m GitInfo Source #

data GitHashException Source #

Exceptions which can occur when using this library's functions.

Since: 0.1.0.0

Constructors

GHECouldn'tReadFile !FilePath !IOException |
GHEInvalidCommitCount !FilePath !String |
GHEInvalidGitFile !String |
GHEGitRunFailed !FilePath ![String] !ExitCode !String !String |
GHEGitRunException !FilePath ![String] !IOException |

#### Instances

Instances details

Exception GitHashException Source # |
Instance details Defined in GitHash Methods toException :: GitHashException -> SomeException Source # fromException :: SomeException -> Maybe GitHashException Source # displayException :: GitHashException -> String Source # backtraceDesired :: GitHashException -> Bool Source #
Show GitHashException Source # |
Instance details Defined in GitHash Methods showsPrec :: Int -> GitHashException -> ShowS Source # show :: GitHashException -> String Source # showList :: [GitHashException] -> ShowS Source #
Eq GitHashException Source # |
Instance details Defined in GitHash Methods (==) :: GitHashException -> GitHashException -> Bool Source # (/=) :: GitHashException -> GitHashException -> Bool Source #

## Getters

giHash :: GitInfo -> String Source #

The hash of the most recent commit.

Since: 0.1.0.0

giBranch :: GitInfo -> String Source #

The hash of the most recent commit.

Since: 0.1.0.0

giDirty :: GitInfo -> Bool Source #

giCommitDate :: GitInfo -> String Source #

giCommitCount :: GitInfo -> Int Source #

giCommitMessage :: GitInfo -> String Source #

The message of the most recent commit.

Since: 0.1.1.0

giDescribe :: GitInfo -> String Source #

The output of `git describe --always` for the most recent commit.

Since: 0.1.4.0

giTag :: GitInfo -> String Source #

The output of `git describe --always --tags` for the most recent commit.

Since: 0.1.5.0

giFiles :: GitInfo -> [FilePath] Source #

The files used to determine whether recompilation is necessary in splices.

Since: 0.1.7.0

# Creators

getGitInfo :: FilePath -> IO (Either GitHashException GitInfo) Source #

Get the `GitInfo` for the given root directory. Root directory should be the directory containing the `.git` directory.

Since: 0.1.0.0

getGitRoot :: FilePath -> IO (Either GitHashException FilePath) Source #

Get the root directory of the Git repo containing the given file path.

Since: 0.1.0.0

# Template Haskell

tGitInfo :: FilePath -> SpliceQ GitInfo Source #

Load up the `GitInfo` value at compile time for the given directory. Compilation fails if no info is available.

Since: 0.1.0.0

tGitInfoCwd :: SpliceQ GitInfo Source #

Load up the `GitInfo` value at compile time for the current working directory.

Since: 0.1.0.0

tGitInfoTry :: FilePath -> SpliceQ (Either String GitInfo) Source #

Try to load up the `GitInfo` value at compile time for the given directory.

Since: 0.1.2.0

tGitInfoCwdTry :: SpliceQ (Either String GitInfo) Source #

Try to load up the `GitInfo` value at compile time for the current working directory.

Since: 0.1.2.0