Skip to content

feat(core): use plain line-based output when stdout is not a terminal - #5117

Merged
dgibbs64 merged 1 commit into
developfrom
feat/2484-plain-output
Oct 31, 2026
Merged

dgibbs64 merged 1 commit into
developfrom
feat/2484-plain-output

Conversation

@dgibbs64

Copy link
Copy Markdown
Member

Description

Output captured by systemd/journald, cron, containers, pipes or redirected files is hard to read: colour codes, carriage returns and erase-line sequences are written regardless of where stdout goes, and in-place progress messages overwrite each other instead of producing complete lines.

This PR adds a plain output mode, used automatically when stdout is not a terminal ([ ! -t 1 ]). Interactive terminal output is unchanged.

Plain mode (core_messages.sh)

  • No colours, text styles, carriage returns or erase-line sequences.
  • In-place status messages (fn_print_dots, fn_print_ok, etc.) are held instead of printed. A later status message replaces the held one, and an end-of-line status (fn_print_ok_eol_nl, etc.) completes it. The result is one complete line per step showing its final state, which is what the terminal ends up displaying.
  • Held messages are flushed as their own line by fn_print, fn_print_nl, fn_print_header, fn_prompt_yn and core_exit.sh, so nothing is lost.
  • The 30 end-of-line helpers now go through shared fn_print_eol / fn_print_eol_nl helpers.

Before (piped, cat -A):

^[[1m^M^[[K[^[[0m .... ^[[0m]^[[0m Monitoring pmcserver: Checking session^[[0m ... ^[[36mCHECKING^[[0m^[[1m^M^[[K[^[[32m  OK  ^[[0m]^[[0m Monitoring pmcserver: Checking session^[[0m ... ^[[32mOK^[[0m$

After:

[  OK  ] Monitoring pmcserver: Checking session ... OK
[  OK  ] Monitoring pmcserver: Querying port: gamedig: 127.0.0.1:25565 : 0/1 ... DELAY

ansi="off" fix

fn_ansi_loader unconditionally reset creeol to include the erase-line sequence after the colour conditional, and always set the text style variables. ansi="off" now disables all ANSI formatting; on a terminal only the carriage return remains so progress lines still update in place. Also fixes an undefined ${cree} in the non-commandaction branch of fn_print_message.

Direct output outside the shared helpers

  • core_dl.sh: no curl progress bar in plain mode, and the "checking" line is written as a complete line instead of being erased.
  • check_deps.sh: dependency install spinner skipped.
  • command_fastdl.sh, command_mods_remove.sh: tput sc/rc/el cursor handling skipped; each fastdl step still ends with one summary line.

Out of scope: structured output (JSON), passing NO_COLOR/TERM=dumb through to the game server, the dev-detect-* developer commands, and SteamCMD progress output (#3655).

Fixes #2484

Affected servers: all

Type of change

  • Bug fix (a change which fixes an issue).
  • New feature (a change which adds functionality).
  • New Server (new server added).
  • Refactor (restructures existing code).
  • Chore (CI, workflows, tooling or other maintenance).
  • Comment update (typo, spelling, explanation, examples, etc).

Testing

  • Commands/tests run:
    • A harness sourcing core_messages.sh that exercises dots/eol/replace sequences, raw output between messages, the restart countdown and a message left pending at exit, run through a pty (script), a pipe and a file redirect with ansi="on" and ansi="off".
    • On a test server, a throwaway pmcserver container with this branch's modules: monitor, stop, start and details piped and redirected to a file; monitor under a pty with ansi="on" and ansi="off".
    • shellcheck and shfmt -sr -ci -d on all changed files.
  • Result:
    • Pipe and file output identical, complete lines, zero control characters, for all commands. Exit status preserved (PIPESTATUS[0] = 0).
    • Terminal output with ansi="on" byte-identical to the current release.
    • Terminal output with ansi="off" contains no escape sequences.
    • shellcheck clean, shfmt no diff.
  • Environment used (distro/version): Ubuntu 26.04 (gameservermanagers/gameserver:pmc), plus Ubuntu WSL for the harness.

Risk and rollback

  • Risk level: medium. Touches the shared message helpers used by every command; terminal output is unchanged, and plain mode only applies when stdout is not a terminal.
  • Rollback plan: revert this PR.

Breaking changes

  • No breaking changes.
  • Breaking changes included (describe below).

Behaviour note: with ansi="off" on a terminal, bold/italic/underline styling is now also disabled, not only colours. Scripts that parse captured output will see complete lines instead of carriage-return-joined fragments.

Documentation

  • No documentation update required.
  • User documentation update required (LinuxGSM-Docs). The ANSI colours page should mention that output is plain when not attached to a terminal.
  • Developer documentation update required (LinuxGSM-Dev-Docs).

Checklist

PR will not be merged until all steps are complete.

  • This pull request links to an issue ("Fixes", or "Related to" for a partial fix).
  • This pull request uses the develop branch as its base.
  • This pull request subject follows the Conventional Commits standard.
  • This code follows the style guidelines of this project.
  • I have performed a self-review of my code.
  • I have provided a detailed enough description of this PR.

Thank you for your Pull Request!

Output captured by systemd/journald, cron, pipes or redirected files was
full of colour codes, carriage returns and erase-line sequences, and
in-place progress messages overwrote each other instead of producing
complete lines.

When stdout is not a terminal, LinuxGSM now omits all terminal control
sequences. In-place status messages are held until they are replaced,
completed by an end-of-line status or flushed, so each step is written
as one complete line showing its final result. Held messages are
flushed before headers, prompts and on exit.

ansi="off" now consistently disables ANSI formatting: the erase-line
sequence is no longer re-added unconditionally and text styles are only
set when ANSI is enabled.

Direct terminal control outside the shared helpers is also skipped in
plain mode: the download progress bar, the dependency install spinner
and tput cursor handling in fastdl and mods-remove.
@github-actions github-actions Bot added the type: feature New feature or request label Oct 31, 2026
@dgibbs64 dgibbs64 added this to the v26.5.0 milestone Oct 31, 2026
@github-actions github-actions Bot added engine: lwjgl2 Issues related to lwjgl2 engine game: PaperMC Issues related to PaperMC labels Oct 31, 2026
@dgibbs64
dgibbs64 merged commit 68d2697 into develop Oct 31, 2026
37 checks passed
@dgibbs64
dgibbs64 deleted the feat/2484-plain-output branch October 31, 2026 01:25
@dgibbs64 dgibbs64 linked an issue Nov 1, 2026 that may be closed by this pull request
dgibbs64 added a commit to GameServerManagers/LinuxGSM-Docs that referenced this pull request Nov 8, 2026
Related to GameServerManagers/LinuxGSM#5117, released in v26.5.0.

## Changes

- Explain the automatic plain output used for pipes and captured logs.
- Document `ansi="off"` and the limits of the setting for game and SteamCMD output.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

engine: lwjgl2 Issues related to lwjgl2 engine game: PaperMC Issues related to PaperMC type: feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Use plain, line-based output when stdout is not a terminal

1 participant