Snipwise in Practice¶

The other documents under Using Snipwise say what Snipwise does. This one is advice on using it well. Nothing here is enforced, and a project that ignores all of it still works.

Not Every Repetition Is a Snippet¶

A snippet costs a place to keep the text and a snipwise fix after every edit, and it is worth that price when two files would otherwise drift apart unnoticed. A paragraph that appears twice by accident is better deduplicated by rewriting one of the two files.

Keep the Original Where It Belongs¶

• A fragment that several files need in the same words, on equal terms, is what a definition in snipwise.md is for. In this case, write a level-2 heading with the snippet's name between backticks and put the text under it in a code block.

• A sentence that clearly belongs to one file, and that another file happens to repeat, is better left where it belongs, with a [[sources]] rule.

  When some of your software tools write to a file, use that one as the original. The dependencies of Snipwise itself are a clear example of this pattern. They live in the dependencies array of pyproject.toml, which is where uv writes them and where a developer reaches to edit them, so that array is the source and snipwise.md only declares the name. Repeating the requirements in snipwise.md would make that definition the original, and a dependency added by uv add would be reverted by the next snipwise fix.

Say Which Copy to Edit¶

A marker names snipwise.md, which always exists, so a reader who runs into a block always arrives somewhere and learns that what they are looking at is a copy. However, this does not yet say which copy is the one to edit. Snipwise supports multiple conventions for saying which copy is the original. Whichever convention you follow, document it in snipwise.md.

For example, you can write it in prose under the snippet's heading:

## `python-versions`

Maintained in `README.md`, from where Snipwise copies it into the documentation.

A [[sources]] rule answers the same question for Snipwise rather than for a human. Combining the two goes against the "don't repeat yourself" principle, but it is not wrong.

An ambiguity that arises once will arise again, so when snipwise fix asks which copy wins, prefer the [[sources]] rule it prints over reaching for --original again on the next edit.

Run Snipwise by Hand after a Rename¶

Renaming a snippet means editing its markers in every file that holds it, and Snipwise refuses the commit when that rename reaches all but one of them, because the block left behind is a lone copy. Snipwise says nothing when the rename reaches all but two of them, because those two blocks are a snippet like any other and they agree with each other. Running snipwise --verbose by hand lists every snippet Snipwise knows and where its copies are, which is how a name that should not be there is spotted.

Keep the Patterns Narrow¶

Every file that a patterns list selects is read on every run, and a pattern starting with **/ visits every directory of the project. Selecting the directories that actually hold markers keeps a hook fast, and it keeps snipwise fix away from files that were never meant to be rewritten.