I've disabled these two tests on Windows as they are failing the CI (snapshots have one fewer terminal width char?) on 2 of the 3 Windows architectures (so if I changed it to per platform it would still not work) 🤦‍♂️

failures:
    piped_output_with_default_style_flag
    piped_output_with_line_numbers_with_header_grid_style_flag

• Log https://github.com/sharkdp/bat/actions/runs/18563295925/job/52917493767?pr=3438
• 🔴 i686-pc-windows-msvc (windows-2025)
• 🔴 x86_64-pc-windows-msvc (windows-2025)
• 🟢 aarch64-pc-windows-msvc (windows-11-arm)

failures:

---- piped_output_with_default_style_flag stdout ----

thread 'piped_output_with_default_style_flag' panicked at /rustc/1159e78c4747b02ef996e55082b704c09b970588\library\core\src\ops\function.rs:253:5:
Unexpected stdout, failed diff original var
├── original: ─────┬──────────────────────────────────────────────────────────────────────────
│        │ STDIN
│   ─────┼──────────────────────────────────────────────────────────────────────────
│      1 │ hello
│      2 │ world
│   ─────┴──────────────────────────────────────────────────────────────────────────
├── diff: 
│   --- 	orig
│   +++ 	var
│   @@ -1 +1 @@
│   -─────┬──────────────────────────────────────────────────────────────────────────
│   +─────┬─────────────────────────────────────────────────────────────────────────
│   @@ -3 +3 @@
│   -─────┼──────────────────────────────────────────────────────────────────────────
│   +─────┼─────────────────────────────────────────────────────────────────────────
│   @@ -6 +6 @@
│   -─────┴──────────────────────────────────────────────────────────────────────────
│   +─────┴─────────────────────────────────────────────────────────────────────────
└── var as str: ─────┬─────────────────────────────────────────────────────────────────────────
         │ STDIN
    ─────┼─────────────────────────────────────────────────────────────────────────
       1 │ hello
       2 │ world
    ─────┴─────────────────────────────────────────────────────────────────────────

command=`"D:\\a\\bat\\bat\\target\\x86_64-pc-windows-msvc\\debug\\bat.exe" "--no-config" "--style=default"`
stdin=````
hello
world

stderr=""

note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

---- piped_output_with_line_numbers_with_header_grid_style_flag stdout ----

thread 'piped_output_with_line_numbers_with_header_grid_style_flag' panicked at /rustc/1159e78c4747b02ef996e55082b704c09b970588\library\core\src\ops\function.rs:253:5:
Unexpected stdout, failed diff original var
├── original: ─────┬──────────────────────────────────────────────────────────────────────────
│        │ STDIN
│   ─────┼──────────────────────────────────────────────────────────────────────────
│      1 │ hello
│      2 │ world
│   ─────┴──────────────────────────────────────────────────────────────────────────
├── diff: 
│   --- 	orig
│   +++ 	var
│   @@ -1 +1 @@
│   -─────┬──────────────────────────────────────────────────────────────────────────
│   +─────┬─────────────────────────────────────────────────────────────────────────
│   @@ -3 +3 @@
│   -─────┼──────────────────────────────────────────────────────────────────────────
│   +─────┼─────────────────────────────────────────────────────────────────────────
│   @@ -6 +6 @@
│   -─────┴──────────────────────────────────────────────────────────────────────────
│   +─────┴─────────────────────────────────────────────────────────────────────────
└── var as str: ─────┬─────────────────────────────────────────────────────────────────────────
         │ STDIN
    ─────┼─────────────────────────────────────────────────────────────────────────
       1 │ hello
       2 │ world
    ─────┴─────────────────────────────────────────────────────────────────────────

command=`"D:\\a\\bat\\bat\\target\\x86_64-pc-windows-msvc\\debug\\bat.exe" "--no-config" "--style=header,grid,numbers"`
stdin=````
hello
world

stderr=""

I recently noticed I cannot pipe bat -n output anywhere

Isn't that what the --decorations flag has been used for ?

bat --decorations=always -nr :4 Cargo.toml | cat
   1 [package]
   2 authors = ["David Peter <mail@david-peter.de>"]
   3 categories = ["command-line-utilities"]
   4 description = "A cat(1) clone with wings."

I recently noticed I cannot pipe bat -n output anywhere

Isn't that what the --decorations flag has been used for ?

I meant bat -n with no further flags cannot pipe, as discussed in #3316 it is documented as the design that these should pipe, but it wasn't implemented:

The description on --style is misleading. It says "auto: same as 'full', unless the output is piped." and "full: enables all available components (default)".

This is ultimately about nicer default behaviour for piping, as #2983 was, and keeping to the original design/better ergonomics.

It makes bat's behavior more complex. The rule is no longer "always act like cat
when piped." Instead, it becomes: "act like cat when piped, unless you use
--number (which makes it behave like cat -n) or explicitly set a --style that
isn't plain or auto." While this is arguably more intuitive, it's a departure
from the simple, documented rule.

Ah I hadn’t seen those man page sections before.

It makes bat's behavior more complex.

I'd say it changes the behaviour rather than making it more complex.

The rule is no longer "always act like cat when piped."

Yes, that's exactly the point - this was the requested change in #2935 (agreed to be worked on in 2024, did not land in #2983).

Instead, it becomes: "act like cat when piped, unless you use --number (which makes it behave like cat -n) or explicitly set a --style that isn't plain or auto."

I think this phrasing is unnecessarily verbose. The simpler way to describe it is:

act like cat when piped, unless you explicitly set a non-auto style.

Two clarifications:

• There's no need to mention plain in the exceptions, piping with plain style looks the same as cat anyway
• There's no need to single out --number, it's just a style alias and is already covered by "explicitly set a style"

Based on the man page you quoted, I thought this was already the intended functionality: that the auto style adapts to piping, while explicit styles like default or numbers would work regardless.

While this is arguably more intuitive, it's a departure from the simple, documented rule.

To me, intuitive = simple. If someone explicitly requests a style with -n or --style=numbers, they expect that style when piping.

I find it undesirable for bat to behave like cat when piped, and my impression from the issue tracker is that others agree.

I understood from #2935 and the discussion on the previous PR that this behavior change was desired. If there's still disagreement about whether this should change at all, I'm not sure how to proceed. I took it I was implementing a requested feature.

The key principle: when someone explicitly requests a style, honour it. Default behaviour (no flags) is preserved for backwards compatibility.

I'll update the man page sections to reflect this behavior change:

@@ -1,3 +1,4 @@
 Whenever the output of {{PROJECT_EXECUTABLE}} goes to a non-interactive terminal, i.e. when the 
 output is piped into another process or into a file, {{PROJECT_EXECUTABLE}} will act as a drop-in 
-replacement for cat(1) and fall back to printing the plain file contents.
+replacement for cat(1) and fall back to printing the plain file contents,
+unless an explicit style is requested.

@@ -2,5 +2,6 @@
 .IP 
 Specify when to use the decorations that have been specified via '\-\-style'. The 
-automatic mode only enables decorations if an interactive terminal is detected. Possible 
-values: *auto*, never, always.
+automatic mode only enables decorations if an interactive terminal is detected. The 
+always mode will show decorations even when piping output. Possible 
+values: *auto*, never, always.

• Man page amended accordingly

I then looked for other docs with the same substring to edit likewise

louis 🌟 ~/dev/bat $ rg -l 'Specify when to use the dec'
src/bin/bat/clap_app.rs
assets/manual/bat.1.in
doc/long-help.txt
tests/syntax-tests/highlighted/Manpage/bat-0.16.man
tests/syntax-tests/source/Manpage/bat-0.16.man

• Other docs reviewed:

  • src/bin/bat/clap_app.rs amended to produce the same as docs/long-help.txt
  • docs/long-help.txt amended to match the man page
  • tests/syntax-tests/highlighted/Manpage/bat-0.16.man - man pages for published version 0.16, left as is
  • tests/syntax-tests/source/Manpage/bat-0.16.man - man pages for published version 0.16, left as is

• Docs tests are passing again

The README also mentions cat-like behaviour in two places (file concatenation and xclip examples), but I'd leave these as is since they still work as shown. The modifier "except if a style is set" could be added, but I think this is sufficiently intuitive/already documented that it would be unnecessary.

👍 Ready for re-review, taking back out of draft

Until now, bat behaved predictably: it showed decorations only in interactive
terminals, stripping them in non‑interactive output unless explicitly forced
(e.g., --decorations=always, --color=always, or --force-colorization).

The proposed change breaks this for some flags. Users would see decorations in
non-interactive output for certain flags but not others. For example, --diff
produces decorations that don't appear in non-interactive terminals, undermining
intuitive flag usage.

I got accustomed to interactive viewing and have learned over the years that
decorations don't carry over unless forced. For the command below, I wouldn't
expect the style to appear in the output:

BAT_OPTS='--style=header,grid' bat README.md | wc -l

If line numbers in piped output is the major reason, users can set the
decorations flag in their config file or use an alias. This solves the issue
without breaking consistency.

• Ref: https://github.com/sharkdp/bat#customization

Thanks for the feedback, to address your points:

The change only affects behaviour when users explicitly pass style flags like -n or --style=numbers (including when set in BAT_OPTS). Default behaviour (no flags/env vars) stays the same, so backward compatibility is preserved. This aligns with the documented behaviour of the auto style.

The principle: if someone explicitly asks for a style, honour it. This matches how other Unix tools work. cat -n preserves numbers when piped, and tail -n with multiple files preserves header decorations. See demos below.

On --diff: I tried it and since diff isn't a style component, it already uses the default auto style behaviour when piped, so no change needed there (see Diff Demo below).

On BAT_OPTS: If someone explicitly sets a style via BAT_OPTS, it's equivalent to setting it on the command line. They can add --decorations=always if they want to ensure decorations pipe.

The logic and compatibility were validated in previous reviews. The implementation is consistent with both the documentation and existing auto behaviour. I'm confident this is the right approach, but I'm open to addressing specific technical concerns if there are any.

Demos

Diff Demo

Behaviour is unchanged:

louis 🌟 ~/dev/bat $ bat --diff README.md
───────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
       │ File: README.md
───────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 911   │ 
 912   │ ## Project goals and alternatives
 913 ~ │ hello
 914   │ `bat` tries to achieve the following goals:
 915   │ 
───────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
louis 🌟 ~/dev/bat $ bat --diff README.md | wc -l
5
louis 🌟 ~/dev/bat $ ./target/release/bat --diff README.md | wc -l
5

Cat Demo

Comparing bat -n behavior with cat -n when piping:

louis 🌟 ~/dev/bat $ echo "hello" | cat | wc -c
6
louis 🌟 ~/dev/bat $ echo "hello" | cat -n | wc -c
13
louis 🌟 ~/dev/bat $ echo "hello" | bat | wc -c
6
louis 🌟 ~/dev/bat $ echo "hello" | bat -n | wc -c
6

With this PR, bat -n behaves like cat -n (preserves line numbers when piped):

louis 🌟 ~/dev/bat $ echo "hello" | ./target/release/bat -n | wc -c
11

Tail Demo

Headers are preserved when piped (similar to bat's header/grid decorations):

louis 🌟 ~/dev/bat $ tail -n999 <(echo "foo") <(echo "bar")
==> /dev/fd/63 <==
foo

==> /dev/fd/62 <==
bar
louis 🌟 ~/dev/bat $ tail -n999 <(echo "foo") <(echo "bar") | cat
==> /dev/fd/63 <==
foo

==> /dev/fd/62 <==
bar

@LangLangBart thanks for sharing your concerns. I understand that these changes may break behavior you are used to. But, as we have had a number of people open issues about it, and the wording in the documentation generally suggesting it should work the way it does in this PR, along with the cat -n piping behavior, I'm going to merge it. If we get lots of complaints, we can certainly revisit it again. Thanks for your understanding.

Just an FYI, apparently some workflows (aliasing cat with specific arguments) have been disrupted due to this change: #3445
Maybe you can help think of the best way forward please @lmmx. Ideally we want to make everyone happy 😅

Sorry @keith-hall I was reviewing bug reports in here this morning and did not spot this 🤦‍♂️ Taking a look now

Maybe you can help think of the best way forward please @lmmx.

That issue seems to be addressed already, not sure what the ask is here @keith-hall but happy to think about any further accomodations. Were there any other reports or just this one so far?

That cat <&… pattern can be seen elsewhere (source) and so can command cat <&… (source)

I personally think aliasing cat with a style is a bit radical, and I think it’s fair to expect that to not be smooth sailing!

It’s much more common if you look at people’s shared dotfiles for them to do it with --style=plain or just bat alone(source), neither of which would be affected.

That issue seems to be addressed already, not sure what the ask is here @keith-hall but happy to think about any further accomodations. Were there any other reports or just this one so far?

Just this one so far that I have seen. I guess I just want us to be prepared in case more come in. I completely agree about aliasing cat 😉 but as it is mentioned in the Readme, we kinda have to support it and try to behave in a way that doesn't break too much...

I was wondering whether it would be safer to only fix -n specifically when it is on the command line (ignoring env vars and config) and in other cases, update the documentation to refer to --decorations. But that also complicates things from a user's perspective - having some arguments work differently when on the command line would be highly unintuitive. So I don't really like that solution 😅

Probably we can leave things as they are for now. Thanks for checking common usage 👍

I personally think aliasing cat with a style is a bit radical, and I think it’s fair to expect that to not be smooth sailing!

I do understand that aliasing cat is bound to break sometimes but in this case I don't see why it is considered radical though.

The way I see it the decorations behave in a confusing way now.

# displays with decorations but does not carry the decorations when piped to something else
bat --paging="never" filename.txt

# displays with decorations and carries the decorations when piped to something else
export BAT_STYLE="header-filename,header-filesize,grid"
bat --paging="never" filename.txt
or
bat --style="header-filename,header-filesize,grid" --paging="never" filename.txt

I always assumed not carrying decorations was deliberate choice to avoid issues when piped to something else but if that is not the case then may be we should unify behaviour in the above case as well.

Probably we can leave things as they are for now.

is @sharkdp still around ?

I personally think aliasing cat with a style is a bit radical, and I think it's fair to expect that to not be smooth sailing!

I do understand that aliasing cat is bound to break sometimes but in this case I don't see why it is considered radical though.

Perhaps "radical" was too strong - I meant that using bat as a "drop-in replacement" (as quoted in the man page) refers to unconfigured behaviour, whilst custom style configurations are a different use case. The PR preserves default (unconfigured) behaviour; extending that guarantee to all possible style configurations would require different design choices.