Typed version of Development.GitRev.

Since: 0.1

These functions are simple, merely a typed version of Development.GitRev's API.

NOTE: These functions do not error if git fails to run, opting instead to return some default value (e.g. string UNKNOWN, boolean False).

These functions allow defining custom behavior. For instance, using the primitive gitHashQ and combinator projectError, we can define a variant of gitHash that instead fails to compile if there are any problems with git:

-- simplified type signatures
qToCode      :: Q a -> Code Q a
projectError :: Q (Either e a) -> Q a
gitHashQ     :: Q (Either GitError String)

>>> :{
  let gitHashOrDie :: Code Q String
      gitHashOrDie = qToCode $ projectError gitHashQ
:}

We can also define a function that falls back to an environment variable, in case the git command fails. firstSuccessQ takes the first action that returns Right.

firstSuccessQ :: NonEmpty (Q (Either e a)) -> Q (Either (Errors e) a)

-- unifying errors
embedGitError :: Q (Either GitError a) -> Q (Either GitRevError a)
embedEnvError :: Q (Either EnvError a) -> Q (Either GitRevError a)

-- look up environment variable
envValQ :: String -> Q (Either EnvError String)

>>> :{
  let gitHashEnv :: String -> Code Q (Either (Errors GitRevError) String)
      gitHashEnv var =
        qToCode $
          firstSuccessQ
            -- using -XOverloadedLists to make this a little nicer
            -- syntactically.
            [ embedGitError gitHashQ,
              embedEnvError $ envValQ var
            ]
:}

Naturally, these can be combined:

>>> :{
  let gitHashEnvOrDie :: String -> Code Q String
      gitHashEnvOrDie var =
        qToCode
          . projectError
          $ firstSuccessQ
            [ embedGitError gitHashQ,
              embedEnvError $ envValQ var
            ]
:}

Custom definitions are particularly useful for "out-of-tree" builds, where the build takes place outside of the normal git tree.

These builds present a problem, as we normally rely on building in the project directory where the .git directory is easy to locate. For example, while gitHash will work for 'cabal build', it will not work for 'nix build' or 'cabal install'. Fortunately, there are workarounds, both relying on passing the right data via environment variables.

1. Passing the git directory.

   For situations where we can pass the current directory during installation e.g.

   $ export EXAMPLE_HOME=$(pwd); cabal install example

   We can use

   runGitInEnvDirQ :: String -> Q (Either GitError a) -> Q (Either GitRevError a)
   

   to define

   >>> :{
     let gitHashSrcDir :: Code Q String
         gitHashSrcDir =
           qToCode
           . projectStringUnknown
           $ firstSuccessQ
             [ -- 1. We first try normal gitHashQ.
               embedGitError gitHashQ,
               -- 2. If that fails, we try again in the directory pointed
               --    to by "EXAMPLE_HOME".
               runGitInEnvDirQ "EXAMPLE_HOME" gitHashQ
             ]
   :}
   

   If the initial call to gitHashQ fails, then we will try again, running the command from the directory pointed to by EXAMPLE_HOME.

2. Passing the value itself.

   This approach can work well with nix, as nix flakes provides a variety of revisions via its self interface. For example:

     # Injecting the git hash via EXAMPLE_HASH where drv is the normal
     # derivation.
     drv.overrideAttrs (oldAttrs: {
       # Also: self.shortRev, self.dirtyShortRev
       EXAMPLE_HASH = "${self.rev or self.dirtyRev}";
     });
   

   Then we can define

   >>> :{
     let gitHashVal :: Code Q String
         gitHashVal =
           qToCode
           . projectStringUnknown
           $ firstSuccessQ
             [ -- 1. We first try normal gitHashQ.
               embedGitError gitHashQ,
               -- 2. If that fails, get the value directly from
               --    "EXAMPLE_HASH".
               embedEnvError $ envValQ "EXAMPLE_HASH"
             ]
   :}
   

   Once again, if the first attempt fails, we will run the second action, looking for the value of EXAMPLE_HASH.

Finally, we can compose these together to make a function that works for all three cases:

>>> :{
  let gitHashValSrc :: Code Q String
      gitHashValSrc =
        qToCode
          . projectStringUnknown
          $ firstSuccessQ
            [ embedGitError gitHashQ,
              runGitInEnvDirQ "EXAMPLE_HOME" gitHashQ,
              embedEnvError $ envValQ "EXAMPLE_HASH"
            ]
:}

Using the typed interfaced, it is easy to combine multiple queries in a safe way.

>>> :{
  import Control.Applicative (liftA3)
  -- | Returns (date, hash, short hash)
  gitComplexData :: Code Q (String, String, String)
  gitComplexData = toCode qs
    where
      toCode = qToCode . projectError
      qs =
        firstSuccessQ
          [ embedGitError gitComplexDataFromGitQ,
            runGitInEnvDirQ "EXAMPLE_HOME" gitComplexDataFromGitQ
          ]
  gitComplexDataFromGitQ :: Q (Either GitError (String, String, String))
  gitComplexDataFromGitQ = do
    -- custom command for commit YYYY-MM-DD
    d <- runGitQ ["log", "HEAD", "-1", "--format=%cs"] IdxNotUsed
    h <- gitHashQ
    sh <- gitShortHashQ
    pure $ liftA3 (,,) d h sh
:}

This section allows looking up data via environment variables.

Warning: caching

Suppose we install an executable example-exe, that depends on example-lib, where the latter contains a TH splice for env var FOO. We first install via:

export FOO=A; cabal install example-exe --installdir=build --overwrite-policy=always

This will build example-lib with A in the splice.

Now suppose we run cabal clean (or delete the build directory e.g. dist-newstyle) and run:

export FOO=B; cabal install example-exe --installdir=build --overwrite-policy=always

What will the result of the splice be? Probably still A! The problem is that cabal does not know that the environment has changed, hence it detects no changes, and example-lib is not re-installed.

The solution is to manually delete the library example-lib, which probably exists in the state directory e.g. ~/.local/state/cabal/store/ghc-9.8.4-inplace.

As alluded to above, Q's default semigroup instance is not lazy enough:

>>> :{
  $$( qToCode $
      (runIO (putStrLn "in q1") $> (Right "q1") :: Q (Either () String))
        <> (runIO (putStrLn "in q2") $> Left ())
    )
:}
in q1
in q2
Right "q1"

For this reason, we introduce QFirst:

mkQFirst :: Q (Either e a) -> QFirst e a
unQFirst :: QFirst e a -> Q (Either (Errors e) a)

>>> :{
  $$( qToCode $ unQFirst $
      (mkQFirst $ runIO (putStrLn "in q1") $> (Right "q1") :: QFirst () String)
        <> (mkQFirst $ runIO (putStrLn "in q2") $> Left ())
    )
:}
in q1
Right "q1"

The function

  firstSuccessQ :: NonEmpty (Q (Either e a)) -> Q (Either (Errors e) a)

utilizes QFirst for sequencing a series of Q actions, stopping after the first success.