Support for `--staged-only` Flag

[hsjobeki]

Feature Request: Support for --staged-only Flag

Is your feature request related to a problem? Please describe.

Yes. When running treefmt natively on a project with partially staged changes, the formatter operates on both staged and unstaged content. For example:

• Staged:
  foo.nix (lines 10–20) — has formatting issues
• Unstaged:
  foo.nix (lines 80–81) — contains the formatting fix, but is unstaged

Because treefmt formats the entire file, it may end up accepting files with unstages formatting fixes as well. Which makes it unsutable as a pre-commit tool on its own.

This becomes an issue when using treefmt as part of a pre-commit hook. Tools like [git-hooks.nix](https://github.com/cachix/git-hooks.nix) are capable of extracting only staged changes, but they bring their own ecosystem. This adds overhead, complexity, and potential integration friction.

Describe the solution you'd like

I'd like treefmt to support a native --staged-only flag, which restricts formatting to only the staged portions of files. This would enable native use of treefmt in pre-commit workflows without (mentioned) external wrappers.

Describe alternatives you've considered

• Using [git-hooks.nix](https://github.com/cachix/git-hooks.nix) with custom eslint formatter derivations scripts to restrict treefmt to staged changes.
  However, this approach introduces:

  • Additional dependencies
  • Complexity in setup and maintenance
  • Friction when dealing with frontend tooling (e.g., aligning eslint plugins with the project)

Running treefmt directly is far simpler — if it supported "staged-only" formatting that would be awesome.

Example of interactions

# Initial state
$ git status

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   foo.nix

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   foo.nix

1. Run

treefmt . --staged-only

Expected:

=> treefmt fails because it checks the staged change only.

2. Stage the formatted files
   This makes sense, since we want to build a pre-commit check. Which should check the content of the commit, not local files.

git add foo.nix
treefmt . --staged-only

Expected:

treefmt runs fine. Because we have staged the formatting changes.

EDIT: Maybe we should call this --check-staged-only which fails on change

[jfly]

If we build this, we should name it so it's clear that it's a git specific thing, and probably error/warn if folks use it when not using a git walker. We support non-git walkers such as vanilla source trees, and possibly soon jujutsu.

Using git-hooks.nix with custom eslint formatter derivations scripts to restrict treefmt to staged changes.

Sorry, but I'm not understanding why pre-commit.com isn't a good tool for this. I'm particularly confused by the mention of eslint, as pre-commit is a python project. Could you explain more about this? What are these "custom eslint formatter derivations scripts"?

[hsjobeki]

Sorry, but I'm not understanding why pre-commit.com isn't a good tool for this

As said:

1. Its another tool i need to use
2. Its forcing me to wrap eslint including its plugins into a derivation to pass it to treefmt. (Talking about usage in UI projects where people use npm, etc.)
3. It is a rather complex thing where i could just place a single shell file in .git/hooks/pre-commit Have you ever looked at and tried to debug / understand the .pre-commit-config.yaml generated by git-hooks.nix?

To summarize

Yes, git-hooks.nix great, but it’s a heavier, an external wrapper that may complicate setups. A native git-staged mode in treefmt is simpler, portable, and avoids additional wrapper layers.

[jfly]

2. Its forcing me to wrap eslint including its plugins into a derivation to pass it to treefmt. (Talking about usage in UI projects where people use npm, etc.)

I'm sorry, but I'm still not understanding this point. How is pre-commit.com/git-hooks.nix forcing you to wrap something in derivation, and why is that unnecessary with plain treefmt?

[hsjobeki]

Okay. Actually figured that it is possible to hook up custom hooks that are just local scripts in git-hooks.nix. So just forget about the eslint point....
:) its kind of unrelated. It was just part of a bigger problem i was trying to solve. Also updated the description.

[jfly]

This feels out of scope for treefmt. The git dance you have to do to implement this --check-staged-only logic already exists in pre-commit. Even if we were to implement it in treefmt, people would still want a tool to create/update their .git/hooks/pre-commit file (aka: pre-commit install).

@hsjobeki, how would you feel if we instead added a simple pre-commit wrapper in treefmt-nix? The wrapper would do exactly one thing: invoke treefmt. We'd avoid the "heaviness" that is git-hooks.nix, but we wouldn't have to re-implement pre-commit's useful logic.

[hsjobeki]

people would still want a tool to create/update their .git/hooks/pre-commit file (aka: pre-commit install).

pre-commit install is super easy and native. You don't need external tools for simple setups. Just do:

ln -s somecript ./git/hooks/pre-commit

or

git config core.hooksPath ./myGitTrackedHooks/

People who want to use git-hooks.nix magic are already supported. This is suited for people who like native behavior.

@hsjobeki, how would you feel if we instead added a simple pre-commit wrapper in treefmt-nix?

This should definetly be out of scope. I don't want treefmt to install any hooks.

I wouldn't want a pre-commit wrapper. Thats out of scope for my feature request. I want the ability to configure the git walker myself.
As said installing git hooks is very easy and is what i am doing already.

The git dance you have to do to implement this

Not sure how complex it really is. it is should be easily implementable like this.
I am just not proficient with go yet.

pseudocode

# List all staged files
for file in exec(`git diff --name-only --cache`):
  # get the staged content
  content = exec(`git show :file`)
  # Check the content
  treefmt-check(content)
# Return exit 0 if staged is formatted
# Return failure is staged is unformatted

Treefmt and git-hooks.nix are both wrappers around other formatters. While i like the approach of treefmt more.
git-hooks.nix has the added benefit that it gives the formatters the staged content, but also appears more heavy weight to me.
And i would appreciate if i could just use treefmt for simpler projects, if i could customize the git walker

[brianmcgee]

I think the simplest solution here is to allow customising the args being passed to git ls-files:

treefmt/walk/git.go

Line 41 in cb8d3fa

cmd := exec.Command("git", "ls-files", "--cached", "--others", "--exclude-standard")

Something like --git-ls-args "cached" which would override the default args we are currently passing.

[jfly]

pre-commit install is super easy and native. You don't need external tools for simple setups. Just do:

It's more than that, right? If there's already a symlink you need to check if it's up to date, out of date, or a completely unrelated file/symlink that you need to ask the user to deal with.

Something like --git-ls-args "cached" which would override the default args we are currently passing.

This sounds good to me.

[hsjobeki]

It's more than that, right? If there's already a symlink you need to check if it's up to date, out of date, or a completely unrelated file/symlink that you need to ask the user to deal with.

Not really. In my shell for example i just do git config core.hooksPath=./hooks
This allows me to use my checked in, git-tracked hooks scripts. No symlink magic involved. Since i am already using direnv and contributors should use the nix-shell everyone gets the hook directory installed. Path/environment is controlled by nix-shell. I don't really see obvious downside. Other than running git ls-files with the correct flags, depending on the hook.