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 getHashQ and combinator projectError, we can define a variant of gitHash that instead fails to compile if there are any problems with git:

>>> :{
  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.

>>> :{
  let gitHashEnv :: String -> Code Q (Either (Exceptions GitOrLookupEnvError) String)
      gitHashEnv var =
        qToCode $
          firstSuccessQ
            (embedGitError gitHashQ)
            [embedLookupEnvError $ envValQ var]
:}

Naturally, these can be combined:

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

An example where custom definitions are useful is "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 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. firstSuccessQ ensures we do not run the second action unless the first fails.

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".
             [embedLookupEnvError $ 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)
            [ embedLookupEnvError $ envValQ "EXAMPLE_HASH",
              runGitInEnvDirQ "EXAMPLE_HOME" gitHashQ
            ]
:}

A final note on laziness: 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 the QFirst newtype:

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

The convenience function

  firstSuccessQ :: Q (Either e a) -> [Q (Either e a)] -> Q (Either e a)

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