Introduction

In YAML, the real comparison is usually between |- and >-, not between two identical - characters. Both forms define multi-line block scalars, and the trailing - means "strip the final newline." The important difference is whether line breaks inside the block are preserved literally or folded into spaces.

| Preserves Line Breaks

The | style is called a literal block scalar. It keeps the line breaks as written.

1literal: |-
2  line one
3  line two
4  line three

A YAML parser reads that value as:

line one
line two
line three

Because the block uses |-, the trailing newline at the end is removed. The internal line breaks remain.

This is the right choice when formatting matters, such as shell scripts, generated config snippets, or human-readable text where each line should stay on its own line.

> Folds Most Line Breaks Into Spaces

The > style is called a folded block scalar. It turns most newline characters into spaces.

1folded: >-
2  line one
3  line two
4  line three

That becomes:

line one line two line three

This is useful when you want to write long text across several lines in the YAML file without forcing those line breaks into the final parsed value.

Blank lines and extra indentation still matter. They can preserve paragraph boundaries or nested formatting, so folded style is not the same as blindly removing all newlines.

What the - Chomping Indicator Means

The trailing - in both |- and >- is the chomping indicator. It tells YAML to strip the final newline that would otherwise be kept.

There are three common cases:

• no chomping indicator: keep one final newline
• '-: strip the final newline'
• '+: keep all trailing newlines'

So the difference between |- and >- is not the -. The - behaves the same in both. The difference comes from | versus >.

Choose Based on the Intended Parsed Value

A practical way to decide is to ask whether the final string should contain real line breaks.

Use |- for content such as:

• shell commands where each line matters
• Markdown or text templates that should preserve structure
• embedded code blocks

Use >- for content such as:

• long human-readable messages
• descriptions split across lines for readability in the YAML file
• values that should become one logical paragraph after parsing

A Small Python Example

This Python example shows the difference when loading YAML.

1import yaml
2
3text = """
4literal: |-
5  line one
6  line two
7folded: >-
8  line one
9  line two
10"""
11
12data = yaml.safe_load(text)
13print(repr(data["literal"]))
14print(repr(data["folded"]))

The first value contains an actual newline between the lines. The second contains a space.

Common Pitfalls

• Thinking the difference is about the - when the real difference is | versus >.
• Using folded style for scripts or commands that require literal line breaks.
• Using literal style for long prose and then wondering why extra newlines appear in the parsed string.
• Forgetting that blank lines and indentation still affect folded blocks.
• Assuming all YAML tools display folded and literal values the same way when round-tripping data.

Summary

• '|- preserves internal line breaks and strips the final trailing newline.'
• '>- folds most internal line breaks into spaces and also strips the final trailing newline.'
• The - part means the same thing in both forms.
• Choose | when formatting must be preserved and > when the value should read as wrapped text.
• If you are debugging parsed output, inspect the final string representation rather than relying on how the YAML source looks.