Add document_start_marker option for YAML stores

Prepend '---' to YAML output when enabled, addressing tools like
yamllint and ytt that often expect the document start marker.

Configurable via .sops.yaml or --document-start-marker flag.

Refs #1158

Signed-off-by: david amick <david@davidamick.com>

Author: snarlysodboxer

README.rst

@@ -1472,6 +1472,19 @@ You can enable this with the ``--compact-array-indent`` CLI option or by configu
       yaml:
           compact_array_indent: true
 
+YAML document start marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, SOPS strips the ``---`` document start marker during encryption. This might
+violate linting rules. You can preserve the marker with the ``--document-start-marker``
+CLI option or by configuring ``.sops.yaml`` with:
+
+.. code:: yaml
+
+  stores:
+      yaml:
+          document_start_marker: true
+
 YAML anchors
 ~~~~~~~~~~~~
 
@@ -2144,6 +2157,9 @@ The store configuration object can have the following keys:
     indicator (``"- "``) is considered part of the indentation. Combined with ``indent: 2``,
     this produces output where arrays are flush with their parent key.
 
+  * ``document_start_marker`` (boolean; default ``false``): when enabled, prepends the
+    ``---`` document start marker to the YAML output.
+
 Encryption Protocol
 -------------------
 

cmd/sops/main.go

@@ -1867,6 +1867,10 @@ func main() {
 			Name:  "compact-array-indent",
 			Usage: "use compact YAML array indentation where '- ' is considered part of the indentation",
 		},
+		cli.BoolFlag{
+			Name:  "document-start-marker",
+			Usage: "prepend the YAML document start marker '---' to the output",
+		},
 		cli.BoolFlag{
 			Name:  "verbose",
 			Usage: "Enable verbose logging output",
@@ -2401,6 +2405,9 @@ func outputStore(context *cli.Context, path string) (common.Store, error) {
 	if context.GlobalBool("compact-array-indent") {
 		storesConf.YAML.CompactArrayIndent = true
 	}
+	if context.GlobalBool("document-start-marker") {
+		storesConf.YAML.DocumentStartMarker = true
+	}
 
 	return common.DefaultStoreForPathOrFormat(storesConf, path, context.String("output-type")), nil
 }

config/config.go

@@ -112,8 +112,9 @@ type JSONBinaryStoreConfig struct {
 }
 
 type YAMLStoreConfig struct {
-	Indent             int  `yaml:"indent"`
-	CompactArrayIndent bool `yaml:"compact_array_indent"`
+	Indent              int  `yaml:"indent"`
+	CompactArrayIndent  bool `yaml:"compact_array_indent"`
+	DocumentStartMarker bool `yaml:"document_start_marker"`
 }
 
 type StoresConfig struct {

stores/yaml/store.go

@@ -423,6 +423,9 @@ func (store *Store) EmitEncryptedFile(in sops.Tree) ([]byte, error) {
 		}
 	}
 	e.Close()
+	if store.config.DocumentStartMarker && !bytes.HasPrefix(b.Bytes(), []byte("---")) {
+		return append([]byte("---\n"), b.Bytes()...), nil
+	}
 	return b.Bytes(), nil
 }
 
@@ -456,6 +459,9 @@ func (store *Store) EmitPlainFile(branches sops.TreeBranches) ([]byte, error) {
 		}
 	}
 	e.Close()
+	if store.config.DocumentStartMarker && !bytes.HasPrefix(b.Bytes(), []byte("---")) {
+		return append([]byte("---\n"), b.Bytes()...), nil
+	}
 	return b.Bytes(), nil
 }
 

stores/yaml/store_test.go

@@ -541,6 +541,64 @@ func TestCompactArrayIndentDisabled(t *testing.T) {
 	assert.Equal(t, string(in), string(bytes))
 }
 
+func TestDocumentStartMarker(t *testing.T) {
+	in := []byte(`key: value
+nested:
+    list:
+        - a
+        - b
+`)
+	expected := []byte(`---
+key: value
+nested:
+    list:
+        - a
+        - b
+`)
+	branches, err := (&Store{}).LoadPlainFile(in)
+	assert.Nil(t, err)
+	bytes, err := (&Store{
+		config: config.YAMLStoreConfig{
+			DocumentStartMarker: true,
+		},
+	}).EmitPlainFile(branches)
+	assert.Nil(t, err)
+	assert.Equal(t, string(expected), string(bytes))
+}
+
+func TestDocumentStartMarkerMultiDoc(t *testing.T) {
+	in := []byte(`---
+key1: value1
+---
+key2: value2`)
+	expected := []byte(`---
+key1: value1
+---
+key2: value2
+`)
+	branches, err := (&Store{}).LoadPlainFile(in)
+	assert.Nil(t, err)
+	bytes, err := (&Store{
+		config: config.YAMLStoreConfig{
+			DocumentStartMarker: true,
+		},
+	}).EmitPlainFile(branches)
+	assert.Nil(t, err)
+	assert.Equal(t, string(expected), string(bytes))
+}
+
+func TestDocumentStartMarkerDisabled(t *testing.T) {
+	in := []byte(`key: value
+`)
+	branches, err := (&Store{}).LoadPlainFile(in)
+	assert.Nil(t, err)
+	bytes, err := (&Store{}).EmitPlainFile(branches)
+	assert.Nil(t, err)
+	assert.Equal(t, string(in), string(bytes))
+	// Verify no '---' was prepended
+	assert.False(t, len(bytes) > 3 && string(bytes[:3]) == "---")
+}
+
 func TestHasSopsTopLevelKey(t *testing.T) {
 	ok := (&Store{}).HasSopsTopLevelKey(sops.TreeBranch{
 		sops.TreeItem{