Terminal protocol extension for soft-wrapping prefixes

[tremby]

For CLI applications which produce a lot of output, deciding how to wrap text is tricky. It's especially important when drawing something where indentation or some other prefix matters or makes the output clearer.

Think, for example, of the output of git log --all --graph --oneline --decorate. If this wraps (which it often will), the graph lines get very difficult to follow.

A CLI program has to decide out of 3 options, as far as I can tell:

1. To not limit line length. In this scenario the output will soft-wrap however the terminal emulator needs to wrap it, which means successive lines cannot be indented in a context-aware way. But it means the available width of the terminal emulator is used up, and it can be rewrapped by the terminal if it changes width.

2. To hard-wrap output at an arbitrary point. This will mean it will not take advantage of the full width if the terminal emulator is wider, and it will wrap in an especially ugly way if the terminal emulator is narrower than the chosen width. The program could allow the user to select the wrap width, but the same issues still apply.

3. To determine the terminal's current width and hard-wrap at that point. This will take advantage of whatever the current width is, but it is not dynamic, and so if the terminal grows wider later the width will not be taken advantage of, and if it gets narrower it'll make a mess.

What I propose is a protocol extension to solve the issue.

• An escape sequence which allows the program to tell the terminal emulator at a given point in output what the prefix for soft-wrapped lines should now be. This string (which should support colours etc) would be rendered at the start of each additional line the terminal emulator decides to soft-wrap text to. It may not be rendered at all if the terminal emulator doesn't need to wrap text.
• If necessary, another escape sequence which cancels any previously-given soft-wrapping prefix. But perhaps a new empty soft-wrapping prefix could be given to serve this purpose instead.
• Perhaps another sequence which would set a soft-wrapping suffix? I don't care so much about this but I'm adding it for completeness. I suppose the terminal emulator would reserve space for and include this string on any line currently being soft-wrapped to the next.

Hopefully terminal emulators which don't support this can just ignore them.

Open questions:

• What should the behaviour be if there is not even enough space for the prefix to be printed?
• Are there difficult edge cases if the soft-wrapping prefix is set more than once in a single line?
• Are there performance concerns? If the terminal emulator width changes, a naive implementation would re-evaluate any scrollback history which has a wrapping prefix set. A more sophisticated one would perhaps mark invisible history as dirty, and re-evaluate only visible scrollback. There are no doubt further optimizations possible.

[kovidgoyal]

(3) is the canonical way to implement this and if the terminal emulator is resized, and the user wants to browse the output of some command, they can simply run the command again, or if that is not feasible for some reason (a very niche use case) they can open the command output in a pager with wrapping disabled using the kitty functionality for opening previous command output in pagers. As such I dont see a real need for this. And it has real performance and code complexity drawbacks that IMO make it not worth the tradeoff.

[tremby]

Thanks for your thoughts.

I don't agree that the situation where it's not feasible to run a command again is a very niche use case. A few examples come to mind.

• You may not want to run git log again in the middle of a complicated rebase or similar because the repo state may have changed. Long lines are common, wrapping makes it confusing because it breaks up graph lines.
• You may not want to reopen a system log file again because of new messages, or because logs may have rotated. Long lines are common, indentation from timestamps would make it a lot more readable.
• You may not want to run something like an ansible playbook again. Long lines are common. Indentation info is important when looking at warnings, diffs, etc.

Opening a previous command's output in a pager with wrapping disabled doesn't help much if the lines are very long.

Perhaps you don't resize your terminal very much? I do, and I imagine a lot of other users who use tiling window managers do too.

Where do you imagine the performance issues and code complexity would be? Would performance be affected at any other time than in the moment of resizing? I'd argue that's not really a performance-critical moment, though perhaps you see it differently.

[kovidgoyal]

On Tue, Oct 21, 2025 at 12:34:54PM -0700, Bart Nagel wrote: Thanks for your thoughts. I don't agree that the situation where it's not feasible to run a command again is a very niche use case. A few examples come to mind. - You may not want to run git log again in the middle of a complicated rebase or similar because the repo state may have changed. Long lines are common, wrapping makes it confusing because it breaks up graph lines.

press ctrl+shift+enter and run git log, you arent actually limited to one terminal window these days. kitty will even put you in the same directory you were in if you want.

- You may not want to reopen a system log file again because of new messages, or because logs may have rotated. Long lines are common, indentation from timestamps would make it a lot more readable.

If a log has rotated you can open the rotated version and in any case you open log files in pagers you dont just cat them into the terminal. This use case is completely moot.

- You may not want to run something like an ansible playbook again. Long lines are common. Indentation info is important when looking at warnings, diffs, etc.

So open the output in a pager.

Opening a previous command's output in a pager with wrapping disabled doesn't help much if the lines are very long.

You have ansible playbooks that generate very long lines that additionally have indentation requirements? And you cant just open them in a pager running ina a window of the same or larger width that they were generated in? Definitely an extremely niche use case.

Perhaps you don't resize your terminal very much? I do, and I imagine a lot of other users who use tiling window managers do too.

I use a tiling window manager as it happens, and resize my terminals all the time. I dont however find I run commands that can only be run once that also generate long lines that also have indentation requirements. And if that ever does happen, say once a year, I can just widen my terminal window and read them comfortably again, since kitty reflows text on window resize.

Where do you imagine the performance issues and code complexity would be? Would performance be affected at any other time than in the moment of resizing? I'd argue that's not really a performance-critical moment, though perhaps you see it differently.

I definitely see it differently. resizing already has to reflow text for potentially thousands of lines of scrollback. Anything that makes that slower needs to have *very good* justifications. Not to mention that trying to implement your proposal would require keeping track of unbounded amounts of data per line. kitty currently keeps track of 8 BITS per line. I'm not even going into all the complexity that will come from dealing with escape codes that erase characters, lines, parts of the screen, multiline characters, etc etc. You need to make a much more compelling argument for your use case than you have so far. You are trying to convince me that this is worth the effort and the overhead, I dont much care whether you believe it is or not.

[tremby]

Perhaps I didn't explain the use cases well enough. Yes, sometimes it's fine to just run the command again, or to do so in a new window or in a pager. But the less trivial situations I'm talking about are where the program has already run and you can't simply run it again because either the output will now be different or because it did something destructive. It's irrelevant that "you could run it in a new window" or "you should have run it in a pager" when the ship has already sailed.

[details about perf/complexity]

You need to make a much more compelling argument for your use case than you have so far. You are trying to convince me that this is worth the effort and the overhead,

Yeah fair enough. It sounds a lot more complicated than I imagined/hoped. And yes, it's not anything vital, we've all lived without it all these years, I just thought it'd be a nice improvement. It's something GUI apps can do but terminal emulators cannot, and I thought perhaps that gap could be closed.