gedcom-reports

Genealogy reports built on top of gedcom-lite.

This package provides higher-level report generators for GEDCOM files. Where gedcom-lite answers questions like "who are this person's ancestors?", gedcom-reports produces a complete document — "a 10-generation Sosa-numbered ancestor report with categorized immigrant tables and a colonial-ancestors section, in markdown."

The tools in this package make editorial choices about how family history should be presented. Those choices (region taxonomies, era boundaries, numbering schemes) live in package-level config files that can be overridden on the command line.

Install

pip install gedcom-reports

Or run without installing:

uvx --from gedcom-reports gedcom-ancestor-report --help

Tools

gedcom-ancestor-report

Generates a markdown report of a person's direct ancestors. Sosa-Stradonitz numbered. Categorizes ancestors into immigrant tables by region of birth and into a colonial-ancestors section by birth/death era.

gedcom-ancestor-report tree.ged --root @I1@ --depth 7 --output report.md

Sections produced:

• Per-generation listing of every ancestor, numbered using the Ahnentafel system (#1 = subject, father = 2N, mother = 2N+1).
• Alternate Family Tree sections for each FAMC entry the user did not pick (only when --alternate is passed for that child).
• Optional FAMC Conflicts list (with --show-conflicts).
• Immigrants section with subsections per region (German and Scandinavian, Dutch, French, Spanish and Portuguese, Italian, Irish, Scottish, Welsh, English by default — fully configurable).
• Colonial Ancestors section — colonial immigrants, ancestors born in the colonies, and early US immigrants.

Flags

--root @I1@                   Root individual xref. (required)
--depth N                     Generations to walk (default: 7).
--override "@C@=@F@,@M@"      Pick parents @F@ and @M@ for child @C@.
                              Repeatable. Either parent may be empty.
--alternate @C@               Render an Alternate Family Tree section for
                              child @C@ from any FAMC entries that weren't
                              chosen. Repeatable.
--regions PATH                Path to regions.yaml or regions.json
                              (default: bundled).
--alt-depth N                 Cap depth of alternate family trees
                              (default: --depth).
--show-conflicts              Include a FAMC Conflicts section before the
                              tables.
--colonial / --no-colonial    Include or suppress the Colonial Ancestors
                              section (default: included). Pass
                              --no-colonial for non-US-focused reports.
--output PATH                 Write to a file (default: stdout).

FAMC default behavior

By default, the tool follows only the first FAMC of each individual. This keeps the main tree unambiguous. To choose a different FAMC for an individual, use --override. Overrides are silent — the un-chosen parent set is dropped — unless you also pass --alternate @C@, which surfaces it as a separate Alternate Family Tree section.

This split lets you handle two distinct cases cleanly:

• Reconciling a data-entry error (a person whose mother and father were entered as two separate FAMC families that should have been one) — use --override alone to merge them silently.
• Documenting an unresolved parentage question (sources disagree on someone's biological parents) — use --override and --alternate so both the chosen and rejected parent sets are visible in the report.

If you want to see which ancestors have multiple FAMC entries before deciding on overrides, use --show-conflicts.

Region classification

A YAML/JSON config file controls how birth places are bucketed. The default config ships with the package and includes Germanic, Scandinavian, Dutch, French, Iberian, Italian, Irish, Scottish, Welsh, and English buckets.

The classification is two-pass: any US/colonies keyword in the place string classifies the place as US (excluded from immigrant tables); otherwise regions are tested in config order, first match wins.

To customize, copy the bundled regions.yaml (location reported by gedcom-ancestor-report --print-default-regions) and pass --regions PATH.

Relationship to gedcom-lite

gedcom-lite is the parser and low-level query layer. gedcom-reports sits on top, depends on gedcom-lite, and produces complete documents. This separation keeps the parser free of editorial choices and lets new report types be added here without growing the parser's scope.

License

MIT.