feat: ability to show diff when failing on changes

Closes #1171

Author: scop

cmd/run.go

@@ -17,6 +17,10 @@ func run() *cli.Command {
 		Name:  "fail-on-changes",
 		Usage: "exit with 1 if some of the files were changed",
 	}
+	failOnChangesDiff := &cli.BoolWithInverseFlag{
+		Name:  "fail-on-changes-diff",
+		Usage: "output a diff when failing on changes",
+	}
 
 	return &cli.Command{
 		Name:      "run",
@@ -107,6 +111,10 @@ func run() *cli.Command {
 				value := cmd.Bool("fail-on-changes")
 				args.FailOnChanges = &value
 			}
+			if failOnChangesDiff.IsSet() {
+				value := cmd.Bool("fail-on-changes-diff")
+				args.FailOnChangesDiff = &value
+			}
 
 			if cmd.Args().Len() < 1 {
 				return errors.New("hook name missing")

docs/mdbook/SUMMARY.md

@@ -62,6 +62,7 @@
     - [`piped`](./configuration/piped.md)
     - [`follow`](./configuration/follow.md)
     - [`fail_on_changes`](./configuration/fail_on_changes.md)
+    - [`fail_on_changes_diff`](./configuration/fail_on_changes_diff.md)
     - [`exclude_tags`](./configuration/exclude_tags.md)
     - [`exclude`](./configuration/exclude.md)
     - [`skip`](./configuration/skip.md)

docs/mdbook/configuration/README.md

@@ -54,6 +54,7 @@ The `-local` config can be used without a main config file. This is useful when
   - [`piped`](./piped.md)
   - [`follow`](./follow.md)
   - [`fail_on_changes`](./fail_on_changes.md)
+  - [`fail_on_changes_diff`](./fail_on_changes_diff.md)
   - [`exclude_tags`](./exclude_tags.md)
   - [`exclude`](./exclude.md)
   - [`skip`](./skip.md)

docs/mdbook/configuration/fail_on_changes.md

@@ -7,6 +7,8 @@ The behaviour of lefthook when files (tracked by git) are modified can set by mo
 - `ci`: exit with a non-zero status only when the `CI` environment variable is set. This can be useful when combined with `stage_fixed` to ensure a frictionless devX locally, and a robust CI.
 - `non-ci`: exit with a non-zero status only when the `CI` environment variable is _not_ set. This can be useful in setups where the CI pipeline commits changes automatically, such as [autofix.ci](https://autofix.ci).
 
+See also [`fail_on_changes_diff`](./fail_on_changes_diff.md).
+
 ```yml
 # lefthook.yml
 pre-commit:

docs/mdbook/configuration/fail_on_changes_diff.md

@@ -0,0 +1,19 @@
+# fail_on_changes_diff
+
+When Lefthook exits with a non-zero status as a result of [`fail_on_changes`](./fail_on_changes.md) triggering, it can optionally output a diff of the detected changes.
+
+The default behavior is to output the diff when run in a CI pipeline.
+The `fail_on_changes_diff` boolean configuration parameter can be used to override this.
+
+```yml
+# lefthook.yml
+pre-commit:
+  parallel: true
+  fail_on_changes: "always"
+  fail_on_changes_diff: true
+  commands:
+    lint:
+      run: yarn lint
+    test:
+      run: yarn test
+```

internal/command/run.go

@@ -26,22 +26,23 @@ const (
 var errPipedAndParallelSet = errors.New("conflicting options 'piped' and 'parallel' are set to 'true', remove one of this option from hook group")
 
 type RunArgs struct {
-	NoTTY           bool
-	AllFiles        bool
-	FilesFromStdin  bool
-	Force           bool
-	NoAutoInstall   bool
-	NoStageFixed    bool
-	SkipLFS         bool
-	Verbose         bool
-	FailOnChanges   *bool
-	Hook            string
-	Exclude         []string
-	Files           []string
-	RunOnlyCommands []string
-	RunOnlyJobs     []string
-	RunOnlyTags     []string
-	GitArgs         []string
+	NoTTY             bool
+	AllFiles          bool
+	FilesFromStdin    bool
+	Force             bool
+	NoAutoInstall     bool
+	NoStageFixed      bool
+	SkipLFS           bool
+	Verbose           bool
+	FailOnChanges     *bool
+	FailOnChangesDiff *bool
+	Hook              string
+	Exclude           []string
+	Files             []string
+	RunOnlyCommands   []string
+	RunOnlyJobs       []string
+	RunOnlyTags       []string
+	GitArgs           []string
 }
 
 func (l *Lefthook) Run(ctx context.Context, args RunArgs) error {
@@ -122,6 +123,7 @@ func (l *Lefthook) Run(ctx context.Context, args RunArgs) error {
 	if err != nil {
 		return err
 	}
+	failOnChangesDiff := shouldFailOnChangesDiff(args.FailOnChangesDiff, hook.FailOnChangesDiff)
 
 	// Convert Commands and Scripts into Jobs
 	hook.Jobs = append(hook.Jobs, config.CommandsToJobs(hook.Commands)...)
@@ -131,19 +133,20 @@ func (l *Lefthook) Run(ctx context.Context, args RunArgs) error {
 	args.RunOnlyJobs = append(args.RunOnlyJobs, args.RunOnlyCommands...)
 
 	return runHook(ctx, hook, l.repo, run.Options{
-		DisableTTY:    cfg.NoTTY || args.NoTTY,
-		SkipLFS:       cfg.SkipLFS || args.SkipLFS,
-		Templates:     cfg.Templates,
-		GlobMatcher:   cfg.GlobMatcher,
-		GitArgs:       args.GitArgs,
-		ExcludeFiles:  args.Exclude,
-		Files:         args.Files,
-		Force:         args.Force,
-		NoStageFixed:  args.NoStageFixed,
-		RunOnlyJobs:   args.RunOnlyJobs,
-		RunOnlyTags:   args.RunOnlyTags,
-		SourceDirs:    sourceDirs,
-		FailOnChanges: failOnChanges,
+		DisableTTY:        cfg.NoTTY || args.NoTTY,
+		SkipLFS:           cfg.SkipLFS || args.SkipLFS,
+		Templates:         cfg.Templates,
+		GlobMatcher:       cfg.GlobMatcher,
+		GitArgs:           args.GitArgs,
+		ExcludeFiles:      args.Exclude,
+		Files:             args.Files,
+		Force:             args.Force,
+		NoStageFixed:      args.NoStageFixed,
+		RunOnlyJobs:       args.RunOnlyJobs,
+		RunOnlyTags:       args.RunOnlyTags,
+		SourceDirs:        sourceDirs,
+		FailOnChanges:     failOnChanges,
+		FailOnChangesDiff: failOnChangesDiff,
 	})
 }
 
@@ -229,6 +232,18 @@ func shouldFailOnChanges(fromArg *bool, fromHook string) (bool, error) {
 	}
 }
 
+func shouldFailOnChangesDiff(fromArg *bool, fromHook *bool) bool {
+	if fromArg != nil {
+		return *fromArg
+	}
+	if fromHook != nil {
+		return *fromHook
+	}
+
+	_, ok := os.LookupEnv("CI")
+	return ok
+}
+
 func runHook(ctx context.Context, hook *config.Hook, repo *git.Repository, opts run.Options) error {
 	ctx, stop := signal.NotifyContext(ctx, os.Interrupt)
 	defer stop()

internal/config/hook.go

@@ -3,16 +3,17 @@ package config
 const CMD = "{cmd}"
 
 type Hook struct {
-	Name          string   `json:"-"                         jsonschema:"-"                                                                             koanf:"-"                   mapstructure:"-"               toml:"-"                         yaml:"-"`
-	Parallel      bool     `json:"parallel,omitempty"        mapstructure:"parallel"                                                                    toml:"parallel,omitempty"   yaml:",omitempty"`
-	Piped         bool     `json:"piped,omitempty"           mapstructure:"piped"                                                                       toml:"piped,omitempty"      yaml:",omitempty"`
-	Follow        bool     `json:"follow,omitempty"          mapstructure:"follow"                                                                      toml:"follow,omitempty"     yaml:",omitempty"`
-	FailOnChanges string   `json:"fail_on_changes,omitempty" jsonschema:"enum=true,enum=1,enum=0,enum=false,enum=never,enum=always,enum=ci,enum=non-ci" koanf:"fail_on_changes"     mapstructure:"fail_on_changes" toml:"fail_on_changes,omitempty" yaml:"fail_on_changes,omitempty"`
-	Files         string   `json:"files,omitempty"           mapstructure:"files"                                                                       toml:"files,omitempty"      yaml:",omitempty"`
-	ExcludeTags   []string `json:"exclude_tags,omitempty"    koanf:"exclude_tags"                                                                       mapstructure:"exclude_tags" toml:"exclude_tags,omitempty"  yaml:"exclude_tags,omitempty"`
-	Exclude       []string `json:"exclude,omitempty"         koanf:"exclude"                                                                            mapstructure:"exclude"      toml:"exclude,omitempty"       yaml:"exclude,omitempty"`
-	Skip          any      `json:"skip,omitempty"            jsonschema:"oneof_type=boolean;array"                                                      mapstructure:"skip"         toml:"skip,omitempty,inline"   yaml:",omitempty"`
-	Only          any      `json:"only,omitempty"            jsonschema:"oneof_type=boolean;array"                                                      mapstructure:"only"         toml:"only,omitempty,inline"   yaml:",omitempty"`
+	Name              string   `json:"-"                              jsonschema:"-"                                                                             koanf:"-"                           mapstructure:"-"                      toml:"-"                              yaml:"-"`
+	Parallel          bool     `json:"parallel,omitempty"             mapstructure:"parallel"                                                                    toml:"parallel,omitempty"           yaml:",omitempty"`
+	Piped             bool     `json:"piped,omitempty"                mapstructure:"piped"                                                                       toml:"piped,omitempty"              yaml:",omitempty"`
+	Follow            bool     `json:"follow,omitempty"               mapstructure:"follow"                                                                      toml:"follow,omitempty"             yaml:",omitempty"`
+	FailOnChanges     string   `json:"fail_on_changes,omitempty"      jsonschema:"enum=true,enum=1,enum=0,enum=false,enum=never,enum=always,enum=ci,enum=non-ci" koanf:"fail_on_changes"             mapstructure:"fail_on_changes"        toml:"fail_on_changes,omitempty"      yaml:"fail_on_changes,omitempty"`
+	FailOnChangesDiff *bool    `json:"fail_on_changes_diff,omitempty" koanf:"fail_on_changes_diff"                                                               mapstructure:"fail_on_changes_diff" toml:"fail_on_changes_diff,omitempty" yaml:"fail_on_changes_diff,omitempty"`
+	Files             string   `json:"files,omitempty"                mapstructure:"files"                                                                       toml:"files,omitempty"              yaml:",omitempty"`
+	ExcludeTags       []string `json:"exclude_tags,omitempty"         koanf:"exclude_tags"                                                                       mapstructure:"exclude_tags"         toml:"exclude_tags,omitempty"         yaml:"exclude_tags,omitempty"`
+	Exclude           []string `json:"exclude,omitempty"              koanf:"exclude"                                                                            mapstructure:"exclude"              toml:"exclude,omitempty"              yaml:"exclude,omitempty"`
+	Skip              any      `json:"skip,omitempty"                 jsonschema:"oneof_type=boolean;array"                                                      mapstructure:"skip"                 toml:"skip,omitempty,inline"          yaml:",omitempty"`
+	Only              any      `json:"only,omitempty"                 jsonschema:"oneof_type=boolean;array"                                                      mapstructure:"only"                 toml:"only,omitempty,inline"          yaml:",omitempty"`
 
 	Jobs []*Job `json:"jobs,omitempty" mapstructure:"jobs" toml:"jobs,omitempty" yaml:",omitempty"`
 

internal/config/jsonschema.json

@@ -154,6 +154,9 @@
             "non-ci"
           ]
         },
+        "fail_on_changes_diff": {
+          "type": "boolean"
+        },
         "files": {
           "type": "string"
         },
@@ -439,7 +442,7 @@
       "type": "object"
     }
   },
-  "$comment": "Last updated on 2025.12.01.",
+  "$comment": "Last updated on 2025.12.09.",
   "properties": {
     "min_version": {
       "type": "string",

internal/run/controller/controller.go

@@ -26,19 +26,20 @@ type Controller struct {
 }
 
 type Options struct {
-	GitArgs       []string
-	ExcludeFiles  []string
-	Files         []string
-	RunOnlyJobs   []string
-	RunOnlyTags   []string
-	SourceDirs    []string
-	Templates     map[string]string
-	GlobMatcher   string
-	DisableTTY    bool
-	FailOnChanges bool
-	Force         bool
-	SkipLFS       bool
-	NoStageFixed  bool
+	GitArgs           []string
+	ExcludeFiles      []string
+	Files             []string
+	RunOnlyJobs       []string
+	RunOnlyTags       []string
+	SourceDirs        []string
+	Templates         map[string]string
+	GlobMatcher       string
+	DisableTTY        bool
+	FailOnChanges     bool
+	FailOnChangesDiff bool
+	Force             bool
+	SkipLFS           bool
+	NoStageFixed      bool
 }
 
 func NewController(repo *git.Repository) *Controller {
@@ -76,7 +77,7 @@ func (c *Controller) RunHook(ctx context.Context, opts Options, hook *config.Hoo
 		defer log.StopSpinner()
 	}
 
-	guard := newGuard(c.git, !opts.NoStageFixed && config.HookUsesStagedFiles(hook.Name), opts.FailOnChanges)
+	guard := newGuard(c.git, !opts.NoStageFixed && config.HookUsesStagedFiles(hook.Name), opts.FailOnChanges, opts.FailOnChangesDiff)
 	scope := newScope(hook, opts)
 	err := guard.wrap(func() {
 		if hook.Parallel {

internal/run/controller/guard.go

@@ -3,6 +3,7 @@ package controller
 import (
 	"errors"
 	"maps"
+	"slices"
 
 	"github.com/evilmartians/lefthook/v2/internal/git"
 	"github.com/evilmartians/lefthook/v2/internal/log"
@@ -15,17 +16,19 @@ type guard struct {
 
 	stashUnstagedChanges bool
 	failOnChanges        bool
+	failOnChangesDiff    bool
 
 	didStash             bool
 	partiallyStagedFiles []string
 	changesetBefore      map[string]string
 }
 
-func newGuard(repo *git.Repository, stashUnstagedChanges bool, failOnChanges bool) *guard {
+func newGuard(repo *git.Repository, stashUnstagedChanges bool, failOnChanges bool, failOnChangesDiff bool) *guard {
 	return &guard{
 		git:                  repo,
 		stashUnstagedChanges: stashUnstagedChanges,
 		failOnChanges:        failOnChanges,
+		failOnChangesDiff:    failOnChangesDiff,
 	}
 }
 
@@ -99,6 +102,7 @@ func (g *guard) after() error {
 			log.Warnf("Couldn't get changeset: %s\n", err)
 		}
 		if !maps.Equal(g.changesetBefore, changesetAfter) {
+			g.changesetDiff(changesetAfter)
 			return ErrFailOnChanges
 		}
 	}
@@ -119,3 +123,35 @@ func (g *guard) after() error {
 
 	return nil
 }
+
+func (g *guard) changesetDiff(changesetAfter map[string]string) {
+	if !g.failOnChangesDiff {
+		return
+	}
+	changed := make([]string, 0, len(g.changesetBefore))
+	for f, hashBefore := range g.changesetBefore {
+		if hashAfter, ok := changesetAfter[f]; !ok || hashBefore != hashAfter {
+			changed = append(changed, f)
+		}
+	}
+	for f := range changesetAfter {
+		if _, ok := g.changesetBefore[f]; !ok {
+			changed = append(changed, f)
+		}
+	}
+	if len(changed) == 0 {
+		return
+	}
+	slices.Sort(changed)
+	diffCmd := make([]string, 0, 4) //nolint:mnd // 3 or 4 elements
+	diffCmd = append(diffCmd, "git", "diff")
+	if log.Colorized() {
+		diffCmd = append(diffCmd, "--color")
+	}
+	diffCmd = append(diffCmd, "--")
+	if diff, err := g.git.Git.BatchedCmd(diffCmd, changed); err != nil {
+		log.Warnf("Couldn't diff changed files: %s", err)
+	} else {
+		log.Println(diff)
+	}
+}