---
title: "Reattach a YAML comment to another key in Rust"
url: https://recursiveai.org/oneyaml/rust/cookbook/move-yaml-comment-between-keys/
description: "Move a leading YAML comment from one key to another in Rust so the saved text puts the note above the new key."
version: "1.2.0"
---

# Reattach a YAML comment to another key in Rust

**oneyaml** is a free, open-source YAML library for Rust from Recursive AI. MIT or Apache-2.0, no unsafe code.

[crates.io](https://crates.io/crates/oneyaml) · [GitHub](https://github.com/recursive-ai-oss/oneyaml-rust) · [Docs](https://recursiveai.org/oneyaml/rust/docs/) · [Download example (.zip)](https://recursiveai.org/oneyaml/rust/cookbook/move-yaml-comment-between-keys/move-yaml-comment-between-keys.zip)

Move `# Use TLS` from above `old` to above `new` with `set_leading`. For a comment tied to a key, that key is its owner; a leading comment sits on the line above it.

```shell
cargo add oneyaml
```

```rust
use oneyaml::{Document, NO_COMMENTS};

fn main() {
    let yaml = "# Use TLS\nold: 80\nnew: 443\n";
    let mut doc = Document::parse(yaml)
        .expect("valid YAML");
    let old = doc.get("old").expect("old value");
    let key = old.key().expect("old key").id();
    let notes = doc.comments(key).expect("notes");
    let note = notes.leading()[0]
        .text().to_owned();
    doc.get_mut("old").expect("old value")
        .set_leading(NO_COMMENTS).expect("clear");
    doc.get_mut("new").expect("new value")
        .set_leading([note]).expect("add note");
    print!("{doc}");
}
```

Unzip [the example](https://recursiveai.org/oneyaml/rust/cookbook/move-yaml-comment-between-keys/move-yaml-comment-between-keys.zip), then `cargo run`.

Requires Rust 1.85 or later. The snippet prints the YAML with the comment in its new location:

```text
old: 80
# Use TLS
new: 443
```

## The full program

The program moves the comment while keeping both keys, then uses a fresh copy of the input to show the deletion case. `set_leading` can return `EditError::CommentReattaches` if the inserted lines would be read as belonging to a different owner.

```rust
use oneyaml::{CommentOwner, Document, NO_COMMENTS, path};

fn main() {
    let yaml = "# Use TLS\nold: 80\nnew: 443\n";
    let mut doc = Document::parse(yaml)
        .expect("valid YAML");
    let old = doc.get("old").expect("old value");
    let key = old.key().expect("old key").id();
    let notes = doc.comments(key).expect("notes");
    let note = notes.leading()[0]
        .text().to_owned();
    doc.get_mut("old").expect("old value")
        .set_leading(NO_COMMENTS).expect("clear");
    doc.get_mut("new").expect("new value")
        .set_leading([note]).expect("add note");
    print!("{doc}");

    println!("After removing old with the comment reattached:");
    let mut doc = Document::parse(yaml)
        .expect("valid YAML");
    let comment = doc.comment_ids()[0];
    let new = doc.get("new").expect("new value")
        .key().expect("new key").id();
    doc.attach_comment(comment, CommentOwner::Leading(new))
        .expect("reattach comment");
    let old = doc.id_of(&path!["old"]).expect("old entry");
    let _ = doc.remove_keep_comments(old).expect("remove old");
    let info = doc.explain_comment(comment).expect("kept note");
    assert_eq!(info.owner(), CommentOwner::Leading(new));
    print!("{doc}");
}
```

`cargo run` prints:

```text
old: 80
# Use TLS
new: 443
After removing old with the comment reattached:
# Use TLS
new: 443
```

## Variations

If you’re deleting `old` and `new` is the next entry, you can set the comment’s in-memory owner with `attach_comment`, then use `remove_keep_comments` to keep the line when removing `old`. Use the same `yaml` input and import `CommentOwner` and `path` from the crate:

```rust
let mut doc = Document::parse(yaml)
    .expect("valid YAML");
let comment = doc.comment_ids()[0];
let new = doc.get("new").expect("new value")
    .key().expect("new key").id();
doc.attach_comment(comment, CommentOwner::Leading(new))
    .expect("reattach comment");
let old = doc.id_of(&path!["old"]).expect("old entry");
let _ = doc.remove_keep_comments(old).expect("remove old");
let info = doc.explain_comment(comment).expect("kept note");
assert_eq!(info.owner(), CommentOwner::Leading(new));
print!("{doc}");
```

The resulting YAML is `# Use TLS` above `new: 443`, with no `old` entry. `attach_comment` alone doesn’t change the YAML text, and ordinary `remove_path` can still take the comment line out with `old`.

## Related recipes

- [Find which YAML node owns a comment](https://recursiveai.org/oneyaml/rust/cookbook/explain-yaml-comment-owner/)
- [Remove a YAML key and keep its leading comments](https://recursiveai.org/oneyaml/rust/cookbook/remove-yaml-key-keep-leading-comments/)

## The short answer

Read the existing leading comment, clear it from `old` with `set_leading(NO_COMMENTS)`, and pass its text to `set_leading` on `new`. That changes the YAML itself. To save the change, write `doc.to_string()` after both edits succeed.

## How do you put a comment above a YAML key?

In YAML text, put `#` on its own line above the key, at the same indentation. [`set_leading`](https://github.com/recursive-ai-oss/oneyaml-rust/blob/14445615f5a5b2895fdaa1da7719584ef15d9d6b/crates/oneyaml/src/document/comment_edit.rs#L772-L780) supplies the indentation and `#` prefix. It replaces the entire set of leading comments at the target: if either key has other leading notes you want to keep, include those notes in the corresponding call. Same-line notes aren’t part of that replacement.

## What is the difference between a leading and an inline YAML comment?

A leading comment belongs before an entry; an inline comment, such as `new: 443 # Use TLS`, follows content on the same line. The library calls the latter a *trailing* comment. For a mapping entry, the owner is named by the key node, not by the value node for `443`. That’s why the code calls `.key()` on the result of `get("old")` before asking for the entry’s comments.

[The attachment API](https://github.com/recursive-ai-oss/oneyaml-rust/blob/14445615f5a5b2895fdaa1da7719584ef15d9d6b/crates/oneyaml/src/document/comments.rs#L1550-L1573) overrides the owner in memory without moving the line. If you write the YAML immediately after `attach_comment`, a fresh parse still infers the owner from the old position. Use `set_leading` when both entries should stay and the change must be visible in the file.
