X-Go Gen-code

File Header Reference

Gen-X uses a file annotation system to decide which files it owns and which files belong to you. Every file emitted by the generator begins with a |@@| annotation on its very first line - after the package declaration. Before each Depicter run, Gen-X scans this line in every file in the target project and uses the annotation to determine whether to overwrite the file, leave it untouched, or handle it according to a specialized rule. Understanding this system is essential for making lasting changes to any Gen-X generated application.

How It Works

When you run the Depicter, Gen-X does not blindly overwrite the entire project. Instead, it reads the first line of each file it would normally generate. If the annotation signals that the file has been customized, Gen-X skips it entirely. If the annotation is the default generated value, Gen-X overwrites the file with a freshly generated copy.

This makes the system deterministic: you always know exactly which files will change on the next run based solely on what is written in their first lines.

Annotation Types

The following annotations are currently in use. Legacy annotations are aliases from an earlier version of the system and are still recognized for backwards compatibility.

Annotation Legacy Alias Behavior When to Use
\|@@\| C \|@@\| F File will be overwritten on the next Depicter run Default state for all freshly generated files; leave as-is if you have not modified the file
\|@@\| W \|@@\| O File will be preserved on the next Depicter run Set this after you make any custom change to a generated file

⚠️ Warning: If the annotation is missing or incorrect, Gen-X may treat the file as generated and overwrite it.

Changing an Annotation

Protecting a file from regeneration is a one-line change. Open the file, find the first line, and replace the C annotation with W.

Before (file is owned by the generator and will be overwritten):

// |@@| C

After (file is owned by you and will be preserved):

// |@@| W

The rest of the file content is unchanged. Only the first-line annotation matters to Gen-X.

A complete protected file looks like this:

// src/mae/create_garden/save_entity_step.go
package steps

// |@@| W

import (
    "context"
    "my-app/src/dat/maes"
    "my-app/src/lib/maestro"
    "my-app/src/srv/handlers"
)

type SaveEntityStep struct {
    // your custom fields here
}

💡 Tip: Before committing a batch of custom changes, use your editor’s global search (or grep -r '|@@| C') to audit all file headers in the project. Any file you have modified that still carries |@@| C will be overwritten on the next Depicter run.

Common Mistakes

⚠️ Warning: Forgetting to update the file header is the most common source of lost work in a Gen-X project. Unlike a merge conflict, there is no warning when Gen-X overwrites a file — it simply replaces the content silently. Adopt the habit of updating the header as the very first edit you make to any generated file, before writing any other changes.

⚠️ Warning: Do not change the header of files you have not actually modified. If a file carries |@@| W but its content is unchanged from what the generator would produce, the file will silently diverge from the generator’s output over time as the schema evolves. Only protect files you genuinely need to customize.

Next Steps

Modifying An App
Depicter