Hooks

git-gamble provides his own custom git hooks to enhance the development workflow

These hooks can be used to perform specific actions before and after gambling

Before Gambling (`pre-gamble`)

The pre-gamble hook is executed before the actual gambling process begins

Sometimes, you want to have certain things imperatively done before gambling on the tests

What if something irrelevant was just missing and that forgetting this was not worth starting again ?

Examples :

Formatting
Linting

After Gambling (`post-gamble`)

The post-gamble hook is triggered after the gambling result is known

Sometimes, you want to do actions after the gamble only in some situations

Examples :

Wrong gamble (pass fail or fail pass)
- Suggest to take a break
Good gamble (pass pass or fail fail)
- Congratulate
Failing tests (fail fail)
- Remember to not push on the main branch
Passing tests (pass pass)
- Suggest to push
- Push automatically

Hook Execution and Configuration

Custom hooks are called with arguments :

pre-gamble <GAMBLED>
- pre-gamble hook is executed with one argument <GAMBLED>
post-gamble <GAMBLED> <ACTUAL>
- post-gamble hook is executed with two arguments <GAMBLED> and <ACTUAL>

Where :

<GAMBLED> is pass or fail
<ACTUAL> is pass or fail

Custom hooks of git-gamble are like any other client-side git hooks :

a hook is a file (pre-gamble or post-gamble)
a hook must be in the $GIT_DIR/hooks/ folder
- or in the folder configured by git config core.hooksPath
a hook must be executable
- to make it executable, execute the following command
```
 chmod +x .git/hooks/*-gamble
```
will not be executed if any of these options are used :
- --no-verify
- --dry-run

Examples

Check the hooks' folder for examples of use

post-gamble.real_time_collaboration.sample.sh is specially adapted to near real-time collaboration
post-gamble.assistant.sample.sh is a simple assistant that displays tips based on the result of the gamble
If you are using git-time-keeper
- pre-gamble.time-keeper.sample.sh
- post-gamble.time-keeper.sample.sh

Hooks Execution Lifecycle

The following diagram shows when custom hooks are executed in relation to standard git hooks

flowchart LR
    subgraph git-gamble's hooks' lifecyle
        direction TB
        git-gamble([git-gamble --pass OR --fail])
        --> pre-gamble[pre-gamble pass OR fail]:::gitGambleHookStyle
        --> git_add([git add --all]):::gitGambleInternalStyle
        --> GAMBLE_TEST_COMMAND([exec $GAMBLE_TEST_COMMAND]):::gitGambleInternalStyle
        --> gamble{Gamble result ?}:::gitGambleInternalStyle

        gamble -->|Gamble success| Success
        subgraph Success
            direction TB

            git_commit([git commit]):::gitGambleInternalStyle
            --> pre-commit:::gitHookStyle
            --> prepare-commit-msg[prepare-commit-msg $GIT_DIR/COMMIT_EDITMSG message]:::gitHookStyle
            --> commit-msg[commit-msg $GIT_DIR/COMMIT_EDITMSG]:::gitHookStyle
            --> post-commit:::gitHookStyle
            post-commit --> rewritten?
            rewritten?{{"Last commit rewritten ? When gambling fail after another gamble fail"}}:::gitGambleInternalStyle
            rewritten? -->|Yes| post-rewrite[post-rewrite amend]:::gitHookStyle --> post-gamble-success
            rewritten? -->|No| post-gamble-success
            post-gamble-success[post-gamble pass OR fail success]:::gitGambleHookStyle
        end

        gamble -->|Gamble error| Error
        subgraph Error
            direction TB

            git_reset([git reset --hard]):::gitGambleInternalStyle
            --> post-gamble-error[post-gamble pass OR fail error]:::gitGambleHookStyle
        end
    end

    subgraph Legend
        direction TB

        subgraph Legend_[" "]
            direction LR

            command([Command executed by user])
            git-gamble_command([Command executed by git-gamble]):::gitGambleInternalStyle
            condition{Condition ?}:::gitGambleInternalStyle
        end

        subgraph Hooks
            direction LR

            hook[git's hook]:::gitHookStyle
            hook_with_argument[git's hook first argument second argument]:::gitHookStyle
            git-gamble_hook_with_argument[git-gamble's hook first argument second argument]:::gitGambleHookStyle
        end
    end

    classDef gitHookStyle fill:#f05133,color:black,stroke:black;
    classDef gitGambleHookStyle fill:#5a3730,color:white,stroke:white;
    classDef gitGambleInternalStyle fill:#411d16,color:white,stroke:white;

git-gamble