diffplug / diffplug/selfie

Add a mode which preserves carriage returns

Open
#2 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Kotlin
Stars
101
Forks
18
PR merge metrics
No merged PRs in 30d

Description

Here are two important properties of the `.ss` snapshot files:

- exactly character-for-character accurate, no slop around leading or trailing whitespace, no forbidden characters
- what you see in the snapshot file is exactly what you get, except for the following escaping rules which preserve the above
- the following characters are escaped: `𐝃` -> `𐝃𐝃`, `𐝁` -> `𐝃𐝁` (they are from an [untranslated dead language](https://en.wikipedia.org/wiki/Linear_A))
- if the first character on a line within a snapshot is `╔` then it is replaced with `𐝁` (this preserves ASCII art within snapshots)

This combination of character-accurate + WYSIWYG breaks down in only one place - line endings. You can't see them, and git's complex and poorly understood line-ending-mutation rules mean that most teams can't reliably do source control that differentiates between `\n` and `\r\n`.

Rather than randomly punch users in the face with this triviality, we do the following:

- Internally, every text-based snapshot in spotless-snapshot has a `.replace("\r", "")`, so snapshots will never fail because of line-ending differences
- New `.ss` files are always written using `\n` line endings
- If an `.ss` file is loaded from disk with `\r\n`, it is converted and parsed using `\n`, but will be written back to disk as `\r\n`

However, this means that the snapshots are not *exactly* character-for-character accurate because they do not preserve `\r`. For users that want to preserve `\r`, we could add a mode which preserves the `\r` character if the user uses the `.ss.asar` format

- #1

Adding support for storing `\r` within `.ss` files might be possible (maybe encode them as `𐝃r`?), but doesn't seem like a good idea.

Contributor guide

Open the contributing guide

Research direction

Start by tracing how .ss files and the .ss.asar format are loaded, parsed, and written, including the existing carriage-return normalization described here. Define the mode's behavior around preserving \r and round-tripping files without changing other escaping rules; done means .ss.asar snapshots retain carriage returns while ordinary snapshots keep current behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.