How GEDCOM works

A GEDCOM file is just plain text. Open one in any editor and you’ll see a long list of short lines, each carrying one small piece of information. There’s no hidden binary, no database — your whole family tree is text you can read. This page teaches you to read it. Five minutes here and every recipe that follows will make sense.

A file is a list of lines

Every line has the same simple shape:

level  [@xref@]  TAG  [value]

• a level number,
• an optional cross-reference id (only on the lines that start a record — more on that below),
• a tag that says what kind of information this is,
• and an optional value — the actual content.

So this single line —

1 NAME John /Doe/

— is level 1, tag NAME, value John /Doe/. (The slashes mark the surname, a GEDCOM convention.) That’s the whole grammar. Everything else is combinations of these lines.

Levels make the hierarchy

The level number is what turns a flat list of lines into a tree. A line at level n belongs to the nearest line above it at level n − 1. Increasing the level nests a detail underneath its parent; keeping the level the same adds a sibling.

0 @I1@ INDI
1 NAME John /Doe/
2 GIVN John
2 SURN Doe
1 BIRT
2 DATE 12 MAR 1832
2 PLAC Boston, Massachusetts, USA

Read by indentation, that says: an individual, who has a name (with a given-name and surname nested beneath it) and a birth (with a date and place nested beneath it). GIVN and SURN describe the NAME; DATE and PLAC describe the BIRT. The numbers carry the structure that the indentation only hints at.

Tip

This is exactly what the editor’s Raw mode shows you, line for line. Structured mode draws the same tree with indentation instead of numbers — same content, friendlier view.

Tags name the fact

A tag is a short code — usually three or four letters — that labels the line: NAME, BIRT, DATE, PLAC, SOUR. A tag’s meaning depends on where it sits: DATE under a BIRT is a birth date; the same DATE under a source citation is the date of the citation. Context is everything, which is why the level structure matters.

You don’t have to memorise the tags. The editor’s autocomplete offers only the tags that are valid at your current position, and the embedded spec viewer explains what any tag means and what may nest beneath it.

When the standard has no tag for something you want to record, GEDCOM lets you invent one: a custom tag always starts with an underscore, like _DNA. See When GEDCOM has no tag for it.

Values: text, or a pointer

A line’s value is usually literal text — 12 MAR 1832, Boston, Massachusetts, USA. But some values are pointers: a cross-reference id wrapped in @…@ that names another record rather than holding content directly.

1 FAMS @F1@

This doesn’t store a family — it points to the family record whose id is @F1@. Pointers are how GEDCOM connects things without copying them.

Records and cross-references

A record is a top-level structure: a line at level 0 that carries a cross-reference id. Each gets a unique id so other records can point to it — an individual (INDI), a family (FAM), a source (SOUR), and so on:

0 @I1@ INDI
0 @F1@ FAM
0 @S1@ SOUR

The id is defined on the level-0 line (0 @I1@ INDI) and referenced as a pointer value elsewhere (1 HUSB @I1@). A family record ties people together entirely through pointers:

0 @F1@ FAM
1 HUSB @I1@
1 WIFE @I2@
1 CHIL @I3@

No names appear here — just links to the three individual records. Follow @I1@ and you land on 0 @I1@ INDI, John Doe. In the app you don’t chase ids by eye: ⌘/Ctrl-click a pointer to jump to the record it names.

Two records are special and appear in every file: it opens with 0 HEAD (the header — the GEDCOM version, the software that wrote the file, and similar file-level details) and ends with 0 TRLR (the trailer, which just marks the end). Neither has a cross-reference id.

Structures: reusable blocks

GEDCOM defines some groups of lines once and reuses them in many places. A source citation, for instance, has the same shape whether it sits under a birth, a name, or a death:

2 SOUR @S1@
3 PAGE p. 42

The recipes lean on this: learn the citation block once and you can attach it anywhere. The same goes for places, notes, and addresses.

Long text: CONT (and CONC)

Each piece of text lives on its own line, so GEDCOM needs a way to write text that spans several lines. CONT adds a line break — the value continues on a new line:

1 NOTE Marriage performed at sea
2 CONT aboard the SS Republic.

GEDCOM 5.5 and 5.5.1 have a companion tag, CONC, which continues a value without a break — used to split one long line, because those versions cap a line at 255 characters. GEDCOM 7.0 removed CONC (and the line-length limit); it uses only CONT. You rarely type either by hand: the editor wraps and continues long text for you, and conversion between versions rewrites CONC / CONT correctly.

Version awareness

The grammar above is the same across 5.5, 5.5.1, and 7.0 — lines, levels, tags, pointers. The few grammar-level differences are small — most notably 7.0 drops CONC and the 255-character line limit. What changes far more between versions is which tags are valid and what they mean — and that’s what the rest of the cookbook flags, recipe by recipe.

You don’t have to write it by hand

Knowing the grammar means you can always read your data and reason about it — but Linea Codex writes the lines for you. Autocomplete proposes valid tags and values, validation underlines anything malformed, and the spec viewer is one click away when you want to know what a tag does. The recipes that follow show you what to record; the app handles how to type it.

---

Next: start recording real genealogy — People & names →.