Guides
This page applies the model to a real workflow. Open the guides overview
Using hooks¶
Use Git hooks when you want immediate local feedback before commit and push.
In envctl, hooks exist for one focused reason: keep envctl guard secrets wired into the local Git flow in a visible, repairable way.
When to use this guide¶
Use this page when:
- you want envctl-managed hook protection in a repository
- hook status looks unclear or drifted
- you need to install, repair, force, or remove managed wrappers
If you want the concept, read Hooks first.
Starting point¶
In most repositories, the normal path is:
$ envctl init
$ envctl hooks statusinit attempts to install managed hooks during repository bootstrap. If that does not complete cleanly, inspect or repair hooks explicitly afterwards.
Step 1: check current hook state¶
Typical states:
healthymissingdriftedforeignnot_executableunsupported
Practical reading:
- healthy → protection is in place
- missing → install it
- drifted / not_executable → repair it
- foreign → something else owns that hook name
- unsupported → envctl refuses to manage that hooks path
Step 2: install or repair¶
If wrappers are missing:
If wrappers exist but look wrong:
Both commands stay conservative by default and leave foreign hooks alone.
Step 3: force only when you mean takeover¶
Use --force intentionally
--force allows envctl to overwrite foreign hooks for supported hook names in the effective managed hooks path.
It is not a general “fix everything” switch.
Step 4: remove only envctl-managed wrappers¶
This removes managed wrappers only. It does not remove foreign hooks.
Common branches¶
- if the hooks path is unsupported, fix the Git hooks path first
- if the hooks are foreign, decide whether envctl should really take ownership
- if hooks are healthy but behavior still looks wrong, the issue may be staged content or workflow assumptions, not the wrapper itself
Read next¶
Hooks troubleshooting¶
Go deeper when hook state itself is missing, drifted, foreign, or unsupported.