gedinfo

A command-line utility for querying GEDCOM genealogy files.

Version: 0.24.0

Installation

Requires Python ≥ 3.11.

Installation is optional. You can run gedinfo directly from the repository using ./bin/gedinfo.

To install the package (for convenience or development):

Editable/dev mode (recommended for development):

pip install -e ".[dev]"

Standard installation:

pip install .

Running

You can run gedinfo in several ways:

Without installation: Use the wrapper script directly: ./bin/gedinfo or add bin to your PATH
After installation: Once installed via pip, the gedinfo command is available on your PATH
As a module: Invoke it directly with python -m gedinfo

gedinfo [--version] [--debug] <command> [options] <arguments>

Global options

--version Print the package version and exit
--debug Show a full Python traceback on error instead of a terse message

Configuration

Some GEDCOM files use non-standard (custom) tags whose names vary between databases. gedinfo does not assume any default for these; you declare the tag names your files use in a TOML settings file. There are no built-in defaults — a command that needs an unconfigured tag aborts with a message explaining what to add and where.

Settings are read from two optional files, with the per-directory file taking precedence (merged per key):

User-global: ~/.config/gedinfo/settings.toml (honors $XDG_CONFIG_HOME) — applies to all your GEDCOM files.
Per-directory: .gedinfo.toml beside the GEDCOM file — applies to GEDCOM files in that directory and overrides the user-global file.

Both use a [gedcom_custom_tags] table with these keys:

Key	Controls	Used by
`living`	tag marking a living/private individual	`living` (required); `stat`, `anonymize` (optional)
`secondary_name`	tag holding a secondary/additional name	`givennames --second-name` (required)
`alternate_name`	tag holding a name in an alternate script/language	`givennames --alt-name` (required)

Example ~/.config/gedinfo/settings.toml (or .gedinfo.toml):

[gedcom_custom_tags]
living = "_LIVING"
secondary_name = "NAM2"
alternate_name = "NAMH"

Behaviour when a tag is not configured:

Abort (with guidance): the living command; givennames when --second-name, --alt-name, or -a/--all_names is passed (-a needs both secondary_name and alternate_name).
Degrade gracefully: stat marks its Living line as not configured; anonymize simply does not specially preserve a living tag.

Commands

Commands are grouped below by purpose.

Browsing & lookup

Command	Description
indi	List all individuals in the file
name	Print the full name of an individual by ID
id	Search for individuals by partial name match
names	Print distinct last names for a list of individual IDs
males	List all male individuals
females	List all female individuals
nosex	List individuals with unknown or unspecified sex
noname	List individuals with no name recorded
living	List individuals flagged as living by the configured living tag

Lineage & relationships

Command	Description
relatives	Show the immediate family of an individual (parents, spouses, children)
ancestors	List all ancestors of an individual
descendants	List all descendants of an individual
lastnames	Print distinct ancestor surnames with lineage paths
givennames	Frequency count of given names among ancestors or descendants
gen	Count ancestor and descendant generations for an individual
relationship	Show all relationships between two individuals

Families & structure

Command	Description
fam	List all family records with husband, wife, and children
roots	List root individuals (those with no recorded parents)
leaves	List leaf individuals (those with no recorded children)
disjoint	List the sizes of connected family components

File reports & transforms

Command	Description
stat	Print file statistics (individual count, family count, roots, leaves)
tags	List all GEDCOM tags found in a file with occurrence counts and summaries
calendar	List birth, death, and marriage anniversaries from a GEDCOM file
diff	Compare two GEDCOM files
anonymize	Output a privacy-safe derivative with fake names and locations
strip	Remove GEDCOM lines matching specified tag(s) and their child lines

Interactive

Command	Description
explore	Browse a GEDCOM file interactively in the terminal

indi

List all individuals in the GEDCOM file.

Syntax:

gedinfo indi [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-i: Print IDs only (without @ delimiters), one per line
-n: Print names only, one per line
(default): Print ID and name pairs in the format ID Name

Output: All individuals sorted by ID.

Examples:

# IDs and names (default)
$ gedinfo indi tests/fixtures/simple.ged
I001	John Smith
I002	Mary Jones
I003	Alice Smith
I004	Bob Smith

# IDs only
$ gedinfo indi -i tests/fixtures/simple.ged
I001
I002
I003
I004

# Names only
$ gedinfo indi -n tests/fixtures/simple.ged
John Smith
Mary Jones
Alice Smith
Bob Smith

name

Print the full name of an individual by their ID.

Syntax:

gedinfo name <indi_id> <gedcom_file>

Arguments:

<indi_id>: The GEDCOM individual ID (with or without @ delimiters, e.g. I001)
<gedcom_file>: Path to the GEDCOM file

Output: Prints the name in the format: First /Surname/

Example:

$ gedinfo name I001 tests/fixtures/simple.ged
John /Smith/

id

Search for individuals by partial name match.

Syntax:

gedinfo id <name> <gedcom_file>

Arguments:

<name>: Name fragment to search for. Matched as a case-insensitive substring against first name and last name independently. Slash delimiters (//) around surnames are accepted and ignored.
<gedcom_file>: Path to the GEDCOM file

Output: Prints one line per matching individual in the format:

I001	Display Name

(ID without @ delimiters, a tab, then the display name). Results are sorted by ID.

Example:

$ gedinfo id Smith tests/fixtures/refinements.ged
I001	John Smith
I002	Mary Smithson

names

Print the distinct last names of individuals whose IDs are listed in a file (or from stdin).

Syntax:

gedinfo names <ids_file> <gedcom_file>

Arguments:

<ids_file>: Path to a file containing individual IDs (one per line, with or without @ delimiters), or - to read from stdin
<gedcom_file>: Path to the GEDCOM file

Output: Prints the distinct last names, one per line, in alphabetical order.

Example:

$ cat ids.txt
I001
I002
I004

$ gedinfo names ids.txt tests/fixtures/simple.ged
Johnson
Smith

males

List all male individuals (sex = M) in the GEDCOM file.

Syntax:

gedinfo males [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-i: Print IDs only (without @ delimiters), one per line
-n: Print names only, one per line
(default): Print ID and name pairs in the format ID Name

Output: Male individuals sorted by ID.

Examples:

# IDs and names (default)
$ gedinfo males tests/fixtures/simple.ged
I001	John Smith
I004	Bob Smith

# IDs only
$ gedinfo males -i tests/fixtures/simple.ged
I001
I004

# Names only
$ gedinfo males -n tests/fixtures/simple.ged
John Smith
Bob Smith

females

List all female individuals (sex = F) in the GEDCOM file.

Syntax:

gedinfo females [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-i: Print IDs only (without @ delimiters), one per line
-n: Print names only, one per line
(default): Print ID and name pairs in the format ID Name

Output: Female individuals sorted by ID.

Examples:

# IDs and names (default)
$ gedinfo females tests/fixtures/simple.ged
I002	Mary Jones
I003	Alice Smith

# IDs only
$ gedinfo females -i tests/fixtures/simple.ged
I002
I003

# Names only
$ gedinfo females -n tests/fixtures/simple.ged
Mary Jones
Alice Smith

nosex

List individuals with unknown or unspecified sex (no SEX tag) in the GEDCOM file.

Syntax:

gedinfo nosex [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-i: Print IDs only (without @ delimiters), one per line
-n: Print names only, one per line
(default): Print ID and name pairs in the format ID Name

Output: Individuals with unknown sex sorted by ID.

Examples:

# IDs and names (default)
$ gedinfo nosex tests/fixtures/no_names.ged
I001	(unknown)
I002	Smith
I003	Jane

# IDs only
$ gedinfo nosex -i tests/fixtures/no_names.ged
I001
I002
I003

# Names only
$ gedinfo nosex -n tests/fixtures/no_names.ged
(unknown)
Smith
Jane

noname

List all individuals with no name recorded (no NAME tag in the GEDCOM file).

Syntax:

gedinfo noname [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-i: Print IDs only (without @ delimiters), one per line
-n: Print names only, one per line
-s, --sort {id,name}: Sort output
(default): Print ID and (unknown) pairs in the format ID (unknown)

Output: Unnamed individuals in GEDCOM file order (or sorted if --sort is given).

living

List individuals whose configured living tag (e.g. _LIVING) is set to a truthy value (Y, yes, true). The tag name is read from your settings and has no built-in default; the command aborts with guidance if it is unconfigured (see Configuration).

Syntax:

gedinfo living [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-i: Print IDs only (without @ delimiters), one per line
-n: Print names only, one per line
-s, --sort {id,name}: Sort output by numeric ID order or alphabetically by name. Default is GEDCOM file order.
-v, --invert: Invert the match and list individuals who are not explicitly marked as living (includes those with _LIVING set to N/no/false, those with an empty _LIVING value, and those with no _LIVING tag).

Output: Matching individuals in GEDCOM file order (or sorted if --sort is given). Default format: ID Name per line.

relatives

Show the immediate family of an individual: parents, the individual themselves, spouses, and children per spouse.

Syntax:

gedinfo relatives [options] <indi_id> <gedcom_file>

Arguments:

<indi_id>: The GEDCOM individual ID (with or without @ delimiters)
<gedcom_file>: Path to the GEDCOM file

Options:

-i, --id: Print IDs only (suppress names), one per relative
-n, --name: Print names only (suppress IDs), one per relative
-b, --birth: Also print birth date column
-d, --death: Also print death date column
-m, --marriage: Also print marriage date column (parents' marriage for parent rows; individual's marriage to that spouse for spouse rows; blank for self and children)
-l, --long: Equivalent to -b -d -m (adds all date columns; ID and name follow the -i/-n convention)

If none of -i, -n, -b, -d, -m, -l is specified, the default output shows both ID and name.

Output: One row per relative, tab-separated. The first column is a relationship label: father:, mother:, parent: (unknown sex), self:, husband:, wife:, son:, daughter:, child: (unknown sex). When the individual has children in a family with no recorded other parent, a standalone (unknown spouse): header line is printed before those children. Families with no other parent and no children are skipped.

Example:

$ gedinfo relatives @I001@ tests/fixtures/relatives.ged
father:	I002	John Smith
mother:	I003	Jane Doe
self:	I001	Bob Smith
wife:	I004	Alice Brown
son:	I005	Charlie Smith
daughter:	I006	Diana Smith
wife:	I007	Eve Green
(unknown spouse):
child:	I008	Eddie Smith

$ gedinfo relatives -l @I001@ tests/fixtures/relatives.ged
father:	I002	John Smith	1 JAN 1900	1 JAN 1970	15 JUN 1925
mother:	I003	Jane Doe	5 MAR 1905		15 JUN 1925
self:	I001	Bob Smith	3 APR 1930		
wife:	I004	Alice Brown	7 JUL 1932		10 OCT 1955
son:	I005	Charlie Smith			
daughter:	I006	Diana Smith			
wife:	I007	Eve Green			
(unknown spouse):
child:	I008	Eddie Smith

ancestors

List all ancestors of an individual, including the individual themselves (generation 1).

Syntax:

gedinfo ancestors [options] <indi_id> <gedcom_file>

Arguments:

<indi_id>: The GEDCOM individual ID (with or without @ delimiters)
<gedcom_file>: Path to the GEDCOM file

Options:

-g N, --generations N: Limit traversal to N generations (N ≥ 1). Generation 1 is the subject, generation 2 is parents, etc.
-l, --long: Enable long output mode (generation, path, last name, ID). Cannot be combined with -i or -n.
-s MODE, --sort MODE: Sort order for --long mode. Choices: generation, path, name, id. Default: generation. Requires --long.
-u, --unknown: Include ancestors with no name in --long mode. By default, nameless ancestors are excluded from long-mode output.
-i: Print IDs only (without @ delimiters), one per line (short mode only).
-n: Print names only, one per line (short mode only).

Output (short mode — default): One line per ancestor in BFS traversal order (subject first, then parents, grandparents, etc.). Each line: ID\tFull Name. Use -i or -n for ID-only or name-only output.

Output (long mode — with -l): Tab-separated values: generation, path, full name (first name then last name, or (unknown) if nameless and -u is set), ID. The path uses p (father), m (mother), ? (unknown sex) to describe the relationship chain from the subject. When -s name is used, sorting is by last name (primary) then first name (secondary).

Examples:

# Short mode: all ancestors from I001
$ gedinfo ancestors I001 tests/fixtures/long_ancestors.ged
I001	Jan Novak
I002	Pieter Novak
I003	Anna Muller
I004	Hans Novak
I005	Greta Bauer
I006	Ernst Muller
I007	Lena Weber
I008	Otto Novak
I009	Unknown Svensson

# Long mode: all ancestors
$ gedinfo ancestors -l I001 tests/fixtures/long_ancestors.ged
1		Jan Novak	I001
2	p	Pieter Novak	I002
2	m	Anna Muller	I003
3	pp	Hans Novak	I004
3	pm	Greta Bauer	I005
3	mp	Ernst Muller	I006
3	mm	Lena Weber	I007
4	ppp	Otto Novak	I008
4	pp?	Unknown Svensson	I009

# Long mode: limit to 2 generations, sort by path
$ gedinfo ancestors -l -g 2 -s path I001 tests/fixtures/long_ancestors.ged
1		Jan Novak	I001
2	p	Pieter Novak	I002
2	m	Anna Muller	I003

descendants

List all descendants of an individual, including the individual themselves (generation 1).

Syntax:

gedinfo descendants [options] <indi_id> <gedcom_file>

Arguments:

<indi_id>: The GEDCOM individual ID (with or without @ delimiters)
<gedcom_file>: Path to the GEDCOM file

Options:

-g N, --generations N: Limit traversal to N generations (N ≥ 1). Generation 1 is the subject, generation 2 is children, etc.
-l, --long: Enable long output mode (generation, path, last name, ID). Cannot be combined with -i or -n.
-s MODE, --sort MODE: Sort order for --long mode. Choices: generation, path, name, id. Default: generation. Requires --long.
-u, --unknown: Include descendants with no name in --long mode. By default, nameless descendants are excluded from long-mode output.
-i: Print IDs only (without @ delimiters), one per line (short mode only).
-n: Print names only, one per line (short mode only).

Output (short mode — default): One line per descendant in BFS traversal order (subject first, then children, grandchildren, etc.). Each line: ID\tFull Name. Use -i or -n for ID-only or name-only output.

Output (long mode — with -l): Tab-separated values: generation, path, full name (first name then last name, or (unknown) if nameless and -u is set), ID. The path uses s (son/male), d (daughter/female), ? (unknown sex) to describe the relationship chain from the subject. When -s name is used, sorting is by last name (primary) then first name (secondary).

Examples:

# Short mode: all descendants from I001
$ gedinfo descendants I001 tests/fixtures/descendants.ged
I001	John Smith
I003	Peter Smith
I004	Anna Smith
I006	Tom Smith
I007	Sue Smith

# Long mode: all descendants, sorted by path
$ gedinfo descendants -l -s path I001 tests/fixtures/descendants.ged
1		John Smith	I001
2	s	Peter Smith	I003
3	ss	Tom Smith	I006
3	sd	Sue Smith	I007
2	d	Anna Smith	I004

# Long mode: limit to 2 generations
$ gedinfo descendants -l -g 2 I001 tests/fixtures/descendants.ged
1		John Smith	I001
2	s	Peter Smith	I003
2	d	Anna Smith	I004

lastnames

Print the ancestors of an individual. Supports two output modes: short (names only) and long (detailed paths). In long mode, ancestors from each lineage branch are sorted from purely paternal lines (ppp) to purely maternal lines (mmm).

Syntax:

gedinfo lastnames [options] <indi_id> <gedcom_file>

Arguments:

<indi_id>: The GEDCOM individual ID (with or without @ delimiters, e.g. I001)
<gedcom_file>: Path to the GEDCOM file

Options:

-g N, --generations N: Limit traversal to N generations (N ≥ 1). Generation 1 is the subject, generation 2 is parents, generation 3 is grandparents, etc. If not specified, traverses all generations.
-l, --long: Enable long output mode. Shows detailed ancestor information including generation, path (relationship notation), last name, and ID.
-s MODE, --sort MODE: Sort the output by one of: generation, path, name, or id. This option is only valid with -l. Default sort order depends on mode:
- Long mode (-l): sorts by path (paternal to maternal)
- Short mode: sorts by name (alphabetically)
-u, --unknown: Include ancestors with no name (no NAME tag in the GEDCOM file). By default, nameless ancestors are suppressed. In short mode this flag has no visible effect (nameless ancestors have no last name to print). In --long mode, nameless ancestors appear with '(unknown)' in the last-name field.
-d DIRECTION, --direction DIRECTION: Traversal direction: ancestors/up (default) or descendants/down. Controls whether surnames are collected from ancestors or descendants.

Output (Short Mode - default): Prints the distinct last names of all traversed relatives, one per line, sorted alphabetically. Nameless ancestors are always excluded (they have no last name to print).

Output (Long Mode - with -l): Tab-separated values with four columns:

Generation number (2 for parents, 3 for grandparents, etc.)
Path (lowercase string of p/m/? characters, see below)
Last name (or "(unknown)" if no surname and -u is set)
Individual ID (without @ delimiters)

When the last name is fewer than 8 characters, an extra tab is added to align the ID column. By default, nameless ancestors are omitted from long-mode output; use -u/--unknown to include them.

Path Notation: The path string indicates the sex of each ancestor in the lineage:

p — paternal (male parent)
m — maternal (female parent)
? — unknown or unspecified sex

For example, pp means paternal grandfather, pm means paternal grandmother, mp means maternal grandfather, mm means maternal grandmother.

Branch-Tip Filtering: In long mode, only the most remote reachable ancestor in each lineage branch is shown. Intermediate ancestors are omitted. With -g N, ancestors at generation N and all roots encountered before that limit are printed.

Examples:

# Short mode: all ancestor surnames, alphabetical order
$ gedinfo lastnames I001 tests/fixtures/long_ancestors.ged
Bauer
Muller
Novak
Svensson
Weber

# Long mode: paternal to maternal sorting (default)
$ gedinfo lastnames -l I001 tests/fixtures/long_ancestors.ged
4       ppp     Novak           I008
4       pp?     Svensson        I009
3       pm      Bauer           I005
3       mp      Muller          I006
3       mm      Weber           I007

# Long mode: limit to 3 generations
$ gedinfo lastnames -l -g 3 I001 tests/fixtures/long_ancestors.ged
3       pp      Novak           I004
3       pm      Bauer           I005
3       mp      Muller          I006
3       mm      Weber           I007

# Long mode: sort by generation
$ gedinfo lastnames -l -s generation I001 tests/fixtures/long_ancestors.ged
3       pm      Bauer           I005
3       mp      Muller          I006
3       mm      Weber           I007
4       ppp     Novak           I008
4       pp?     Svensson        I009

# Long mode: sort by last name
$ gedinfo lastnames -l -s name I001 tests/fixtures/long_ancestors.ged
3       pm      Bauer           I005
3       mp      Muller          I006
4       ppp     Novak           I008
4       pp?     Svensson        I009
3       mm      Weber           I007

givennames

Print a frequency count of given names found among relatives in the chosen direction (ancestors or descendants). Results are grouped into three sections — Masculine names, Feminine names, Unknown sex — and empty sections are omitted. Within each section, names are sorted descending by count, then ascending alphabetically.

Syntax:

gedinfo givennames [options] <indi_id> <gedcom_file>

Arguments:

<indi_id>: The GEDCOM individual ID (with or without @ delimiters, e.g., I001 or @I001@)
<gedcom_file>: Path to the GEDCOM file

Options:

-g N, --generations N: Limit traversal to N generations (N ≥ 1). Generation 1 is the subject, generation 2 is parents/children, generation 3 is grandparents/grandchildren, etc. If not specified, traverses all generations.
-2, --second-name: Also include names from the configured secondary-name tag. Requires secondary_name to be configured (see Configuration).
-s MODE, --sort MODE: Sort order within each section. frequency (default) sorts by count descending, then alphabetically for ties. name sorts alphabetically regardless of count.
-x, --alt-name: Also include names from the configured alternate-name tag. Requires alternate_name to be configured (see Configuration).
-a, --all_names: Equivalent to --second-name --alt-name.
-f, --fuzzy: Group name variants together using the bundled variants file (gedinfo/data/name_variants.txt). When multiple variants of the same name appear, they are counted and reported on one line with individual variant counts in parentheses.
-d DIRECTION, --direction DIRECTION: Traversal direction: ancestors or up for ancestors, descendants or down for descendants (default: descendants).

Output: Prints output lines in the format <count>\t<name>, grouped under section headers. Names are printed with an initial capital letter.

Without --fuzzy:

Masculine names:
3	Moshe
2	Abraham

Feminine names:
4	Sarah
1	Miriam

With --fuzzy (when variants are grouped):

Masculine names:
3	Abraham  (Abraham: 2, Abram: 1)

Names with no known variants print without the parenthetical.

Name variants file: The bundled variants file at gedinfo/data/name_variants.txt contains Sephardic/Ashkenazic Jewish name equivalences and can be edited directly. Each non-comment line is one equivalence group of space-separated variants. Lines starting with or containing # are comments.

Examples:

# Descendants (default): given-name counts for all descendants of I001
$ gedinfo givennames I001 tests/fixtures/simple.ged

# Ancestors: given-name counts for all ancestors of I001
$ gedinfo givennames --direction ancestors I001 tests/fixtures/simple.ged
Masculine names:
2	John
1	James

Feminine names:
3	Mary
1	Anne

# Ancestors sorted alphabetically by name
$ gedinfo givennames --direction ancestors --sort name I001 tests/fixtures/simple.ged
Masculine names:
1	James
2	John

Feminine names:
1	Anne
3	Mary

# Fuzzy grouping with secondary names, ancestors only
$ gedinfo givennames --direction ancestors -f -2 I001 tests/fixtures/simple.ged
Masculine names:
3	John  (John: 2, Yohanan: 1)
1	James

gen

Count the maximum number of ascending and descending generations relative to an individual. generations is an alias for gen.

Syntax:

gedinfo gen <indi_id> <gedcom_file>

Arguments:

<indi_id>: The GEDCOM individual ID (with or without @ delimiters, e.g. I001)
<gedcom_file>: Path to the GEDCOM file

Output: A single line with three tab-separated fields:

ancestors: NGA	descendants: NGD	total: NGT

ancestors — generations above the individual (parents = 1, grandparents = 2, …); 0 if none known
descendants — generations below the individual (children = 1, grandchildren = 2, …); 0 if none known
total — ancestors + descendants + 1 (the individual themselves counts as 1)

Example:

$ gedinfo gen I003 tests/fixtures/descendants.ged
ancestors: 1	descendants: 1	total: 3

relationship

Find all common ancestors of two individuals and print each relationship as a formatted block showing the lineage paths from the shared ancestor down to each individual.

Syntax:

gedinfo relationship <first_id> <second_id> <gedcom_file>

Arguments:

<first_id>: First individual ID (with or without @ delimiters, e.g. I001)
<second_id>: Second individual ID (with or without @ delimiters, e.g. I002)
<gedcom_file>: Path to the GEDCOM file

Output: One block per common ancestor, with a blank line between blocks. Nothing is printed when the two individuals share no common ancestor.

Each block has one row per generation. The generation number is shown on the left. When both individuals descend from the common ancestor, row 1 shows the ancestor name in both columns; subsequent rows show the lineage to each individual side by side. When one individual is the direct ancestor of the other, a single column is printed.

Example:

$ gedinfo relationship I003 I004 tests/fixtures/simple.ged
1  John Smith   John Smith
2  Alice Smith  Bob Smith

1  Mary Jones   Mary Jones
2  Alice Smith  Bob Smith

fam

List all family records, showing the family ID, husband, wife, and children.

Syntax:

gedinfo fam [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-i: Print IDs only (without @ delimiters)
-n: Print names only
-s, --sort {id,name}: Sort by numeric ID order or alphabetically by family name. Default is GEDCOM file order.
(default): Print ID and name pairs for the parents

Output: One row per family, tab-separated: family ID, husband, wife, then children. A missing husband or wife shows as (none); a family with no children shows (none) in the children column. Multiple children are comma-separated.

Examples:

# IDs and names (default)
$ gedinfo fam tests/fixtures/relatives.ged
F000	I002	John Smith	I003	Jane Doe	Bob Smith
F001	I001	Bob Smith	I004	Alice Brown	Charlie Smith, Diana Smith
F002	I001	Bob Smith	I007	Eve Green	(none)
F003	I001	Bob Smith	(none)	Eddie Smith

# IDs only
$ gedinfo fam -i tests/fixtures/relatives.ged
F000	I002	I003	I001
F001	I001	I004	I005, I006
F002	I001	I007	(none)
F003	I001	(none)	I008

# Names only
$ gedinfo fam -n tests/fixtures/relatives.ged
F000	John Smith	Jane Doe	Bob Smith
F001	Bob Smith	Alice Brown	Charlie Smith, Diana Smith
F002	Bob Smith	Eve Green	(none)
F003	Bob Smith	(none)	Eddie Smith

roots

Print the root individuals (those with no recorded parents) in the GEDCOM file.

Syntax:

gedinfo roots [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-i: Print IDs only (without @ delimiters), one per line
-n: Print names only, one per line
-s, --sort {id,name}: Sort output by numeric ID order or alphabetically by name. Default is GEDCOM file order.
--spouse: Include roots whose spouse has parents with at least one known name. By default such individuals are suppressed because they likely married into a documented family rather than representing an independent lineage starting point.
-u, --unknown: Include roots with no name at all (no NAME tag in the GEDCOM file). By default, nameless individuals are suppressed.
-a, --all: Include all roots without any suppression. Equivalent to combining --spouse and --unknown. Cannot be combined with --spouse or --unknown.

Output: Root individuals in GEDCOM file order (or sorted if --sort is given). Default format: ID Name per line.

Examples:

# IDs and names (default)
$ gedinfo roots tests/fixtures/simple.ged
I001	John Smith
I002	Mary Jones

# IDs only
$ gedinfo roots -i tests/fixtures/simple.ged
I001
I002

# Names only
$ gedinfo roots -n tests/fixtures/simple.ged
John Smith
Mary Jones

leaves

Print the leaf individuals (those with no recorded children) in the GEDCOM file.

By default, two categories are suppressed (matching roots behaviour):

Nameless leaves — individuals with no NAME tag
Married-in leaves — individuals in a childless family whose spouse has children with another partner

Syntax:

gedinfo leaves [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-i: Print IDs only (without @ delimiters), one per line
-n: Print names only, one per line
-s, --sort {id,name}: Sort output
--spouse: Include married-in leaves (whose spouse has children with another partner). By default such individuals are suppressed.
-u, --unknown: Include leaves with no name at all. By default, nameless individuals are suppressed.
-a, --all: Include all leaves without any suppression. Cannot be combined with --spouse or --unknown.
(default): Print ID and name pairs in the format ID Name

Output: Leaf individuals (after suppression filters) sorted by GEDCOM file order, or by sort key if --sort is given.

Examples:

# IDs and names (default)
$ gedinfo leaves tests/fixtures/simple.ged
I003	Alice Smith
I004	Bob Smith

# IDs only
$ gedinfo leaves -i tests/fixtures/simple.ged
I003
I004

# Names only
$ gedinfo leaves -n tests/fixtures/simple.ged
Alice Smith
Bob Smith

disjoint

Print the sizes of all connected components (disjoint family groups) in the GEDCOM file.

Syntax:

gedinfo disjoint [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-i: Print IDs from each component (without @ delimiters), grouped by component
-n: Print names from each component, grouped by component
--spouse: As per the roots command: include roots whose spouse has parents with at least one known name. When this flag is passed and suppression removes all roots from a connected component, that component is shown with a single placeholder line "(roots suppressed)" instead of individual entries.
-u, --unknown: Include nameless roots (no NAME tag). By default nameless individuals are suppressed.
-a, --all: Include all roots without suppression. Cannot be combined with --spouse or --unknown.
(default): Print the size of each component, one per line

Output: The sizes of disjoint components, one per line. If -i or -n is specified, individuals are grouped by their component with a blank line between groups.

Examples:

# Component sizes (default)
$ gedinfo disjoint tests/fixtures/simple.ged
5
2

# IDs by component
$ gedinfo disjoint -i tests/fixtures/simple.ged
I001
I002
I003
I004

I005
I006

# Names by component
$ gedinfo disjoint -n tests/fixtures/simple.ged
John /Smith/
Alice /Smith/
Jane /Johnson/
Bob /Johnson/

Charlie /Brown/
Diana /Brown/

stat

Print a statistics summary for the GEDCOM file, including counts of individuals (broken down by sex, name completeness, living status, and whether they are roots or leaves), families, generation depth, and number of disjoint family forests.

Syntax:

gedinfo stat [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

--spouse: Include spouse-suppressed individuals in the root count (same criteria as roots --spouse).
-u, --unknown: Include nameless individuals in the root count.
-a, --all: Include all roots in the count. Cannot be combined with --spouse or --unknown.

Output: Human-readable multi-section statistics report.

Example:

$ gedinfo stat tests/fixtures/simple.ged
Individuals: 4
  Males: 2
  Females: 2
  Unknown sex: 0
  Roots (no parents): 2
  Leaves (no children): 2
  No name: 0
  Incomplete name: 0
  Living (_LIVING = Y): 0

Families: 1
  Families with unnamed/incomplete parent: 0
  Families with no children: 0

Generations: 2

Disjoint forests: 1

calendar

List birth, death, and marriage anniversaries from a GEDCOM file, sorted by month and day so that all events on the same calendar date are grouped together.

Syntax:

gedinfo calendar [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-o FILE / --output FILE: write output to FILE instead of stdout
--today: show only events whose day and month match today's date
--thismonth: show only events in the current calendar month
--month MONTHNAME: show only events in the specified month; MONTHNAME can be a full English name or 3-letter abbreviation in any case (e.g. January, jan, JAN)
--dateformat PATTERN: strftime pattern for formatting dates (default: %d %b %Y, e.g. "01 Jan 1801")
--nosep: suppress the blank line printed between groups of events on different days

--today, --thismonth, and --month are mutually exclusive; specifying more than one exits with an error.

Output format: Each event is printed on one line with three TAB-separated fields:

Date (formatted with --dateformat)
Event type — birth, death, or marriage — left-padded to 8 characters
Name(s) — for births and deaths, the individual's full name; for marriages, both spouses joined by &

Events are sorted by month → day → year. A blank line is printed between groups with different day-month values (suppressed with --nosep).

Included / excluded:

Only dates with a complete day, month, and year are included (format: D MON YYYY)
Year-only dates, month-year dates, and approximate/qualified dates (ABT, BEF, AFT, BET…AND) are silently skipped
Individuals with no name produce (unknown) in their event row
Missing spouses in a marriage produce (unknown) for that side

Example:

$ gedinfo calendar tests/fixtures/calendar.ged
01 Jan 1801	birth   	John Doe
02 Jan 1883	death   	John Doe

15 Mar 1820	birth   	Jane Smith
15 Mar 1855	birth   	Bob Jones

03 Apr 1930	death   	Bob Jones

05 Jun 1825	marriage	John Doe & Jane Smith
15 Jun 1900	birth   	Alice Brown

20 Sep 1870	marriage	(unknown) & Jane Smith

$ gedinfo calendar --today tests/fixtures/calendar.ged
$ gedinfo calendar --dateformat "%Y-%m-%d" --nosep tests/fixtures/calendar.ged
1801-01-01	birth   	John Doe
1883-01-02	death   	John Doe
1820-03-15	birth   	Jane Smith
1855-03-15	birth   	Bob Jones
1930-04-03	death   	Bob Jones
1825-06-05	marriage	John Doe & Jane Smith
1900-06-15	birth   	Alice Brown
1870-09-20	marriage	(unknown) & Jane Smith

diff

Compare two GEDCOM files and report individuals and families that were added, removed, or changed. Comparison is ID-based: the same GEDCOM xref ID means the same entity.

Syntax:

gedinfo diff [options] <gedcom1> <gedcom2>

Arguments:

<gedcom1>: First GEDCOM file
<gedcom2>: Second GEDCOM file

Options:

Option	Description
`-l`, `--long`	For each `CHG` entry, show which fields changed and their old/new values
`-s {id,name}`, `--sort`	Sort output by `id` (default, numeric) or `name` (alphabetical)
`-i`	Print IDs only (not compatible with `-l`)
`-n`	Print names only (not compatible with `-l`)
`-a`, `--all`	Compare all model fields including sex, living status, name variants, and notes

Change codes:

CHG — exists in both files but at least one field differs
DEL — exists in the first file only
INS — exists in the second file only

Output: One line per differing individual or family (individuals first, then families). Each line has three TAB-separated fields: ID, name, change code. Use -i or -n to suppress the ID or name column.

With -l, each CHG entry is followed by the changed field names and their old (<) / new (>) values, indented for readability.

Example:

$ gedinfo diff before.ged after.ged
I001    John Smith      CHG
I004    Bob Smith       DEL
I005    New Person      INS
F001    John Smith & Mary Jones CHG

$ gedinfo diff -l before.ged after.ged
I001    John Smith      CHG
  birth_date
    < 1 JAN 1800
    > 2 JAN 1800
I004    Bob Smith       DEL
I005    New Person      INS
F001    John Smith & Mary Jones CHG
  child_ids
    < I003, I004
    > I003

anonymize

Output an anonymized derivative of a GEDCOM file. Names, locations, and notes are replaced with fake-but-realistic data while the family structure (IDs, relationships, dates, sex) is preserved. The output is deterministic: the same input always produces the same anonymized output.

Syntax:

gedinfo anonymize [options] <gedcom_file>

Arguments:

<gedcom_file>: Path to the GEDCOM file

Options:

-o FILE / --output FILE: write output to FILE instead of stdout
--keep FIELD: keep FIELD unchanged (repeatable)
--remove FIELD: strip FIELD from output (repeatable)
--fake FIELD: anonymize FIELD with realistic fake data (repeatable)
--seed NUMBER: seed for the random name/location generator (default: 0)

If the same GEDCOM field is specified in more than one of --keep, --remove, or --fake, the command exits with an error naming the conflicting field.

What is kept unchanged:

All date fields (DATE)
Sex of individuals (SEX)
All structural IDs and family links (HUSB, WIFE, CHIL, FAMC, FAMS)
_LIVING fields
Event container tags (BIRT, DEAT, MARR, etc.)

What is anonymized:

Names (NAME, GIVN, SURN) — fake names matching the original structure:
- Token count is preserved (two-word first name → two-word fake first name)
- Name structure is preserved: first-name-only individuals have no slashes in output; last-name-only individuals retain the /Surname/ format
- Individuals with an empty name (NAME //) have the NAME tag stripped entirely
- Individuals sharing the same original last name receive the same fake last name
- Compound names (multiple tokens) always have distinct tokens — no repetition
- Fake tokens are length-bounded: up to 20 attempts are made to find a token no longer than the original; the shortest candidate is used if none qualifies
Locations (PLAC, ADDR, CITY, STAE, CTRY, POST) — fake place names with the same length-bounding as names; the same original value always maps to the same fake value
Notes (NOTE and continuation lines)

What is stripped:

GEDCOM header content (replaced with a minimal valid header)
All other fields not listed above

Example:

$ gedinfo anonymize family.ged
0 HEAD
1 GEDC
2 VERS 5.5.1
1 CHAR UTF-8
0 @I001@ INDI
1 NAME Richard /Sullivan/
1 SEX M
...

$ gedinfo anonymize --keep OCCU --remove DATE family.ged
$ gedinfo anonymize -o anonymized.ged family.ged

strip

Remove lines matching one or more specified GEDCOM tags from a GEDCOM file. When a tag is removed, all lower-ranking lines nested under it are also removed (e.g. stripping NAME also removes its GIVN/SURN sub-lines).

Syntax:

gedinfo strip [options] <field(s)> <gedcom_file>

Arguments:

<field(s)>: One or more GEDCOM tags to remove (space-separated)
<gedcom_file>: Path to the GEDCOM file

Options:

-o FILE / --output FILE: write output to FILE instead of stdout

Output: The GEDCOM file with all lines for the specified tag(s) — and their child lines — removed. The input file is never modified unless -o is given the same path as the input.

If a specified tag is one whose removal can damage the GEDCOM structure (INDI, FAM, FAMS, FAMC, HUSB, WIFE, CHIL, NAME, GIVN, SURN, HEAD, TRLR), a warning explaining the consequence is printed to stderr for each such tag before the file is processed; the command still proceeds and exits 0.

Example:

$ gedinfo strip NOTE family.ged
0 HEAD
...

$ gedinfo strip -o stripped.ged SOUR OBJE family.ged

$ gedinfo strip FAMC family.ged
Warning: stripping FAMC breaks the link from an individual to their family-as-child record.
0 HEAD
...

explore (TUI mode)

Browse a GEDCOM file interactively in the terminal.

Syntax:

gedinfo explore [[<indi_id>] <gedcom_file>]

Arguments:

<gedcom_file> (optional): Path to the GEDCOM file to open
<indi_id> (optional, requires <gedcom_file>): Individual ID to navigate to on launch

If no arguments are given, the TUI opens in an empty state; press o to load a file from within the browser. With one argument the file is opened at the first individual. With two arguments the first argument is the individual ID to start from and the second is the file.

Layout:

Three columns are shown side by side:

Left — parents of the focused individual
Center — the focused individual and their spouses (cursor lives here)
Right — children of the focused individual

A status pane below the columns shows birth/death dates, parents, spouse count, and children count for the focused individual.

Key bindings:

Key	Action
`j` / `↓`	Move cursor down within center pane
`k` / `↑`	Move cursor up within center pane
`ctrl+d` / `ctrl+u`	Half-page down / up in list views
`ctrl+f` / `ctrl+b`	Full-page down / up in list views
`l` / `→`	Navigate to only child; or enter inline child-selection (multiple children)
`h` / `←`	Navigate to only parent; or enter inline parent-selection (two parents)
`f`	Navigate directly to father (shown as key hint in left pane)
`m`	Navigate directly to mother (shown as key hint in left pane)
`s`	Navigate directly to first spouse (shown as key hint in center pane)
`1`–`9`	Navigate directly to the 1st–9th child (shown as key hints in right pane)
`Enter`	Navigate to selected center item (e.g. a spouse)
`b`	Go back (navigation history)
`r`	Jump to root (oldest ancestor via first-parent path)
`i`	Toggle display of GEDCOM IDs (hidden by default)
`c`	Command palette (stat, roots, leaves, lastnames, givennames, …); each entry shows its letter shortcut highlighted
`/`	Search by name or ID; shows a list when multiple matches
`o`	Open a different GEDCOM file
`q`	Quit

Testing

Run the test suite using pytest from the project root:

pytest -q

Formatting & linting

Ruff handles both linting and formatting. To check (as CI does) run:

ruff check .            # lint
ruff format --check .   # formatting

To auto-fix and format in place:

ruff check --fix .
ruff format .

A .pre-commit-config.yaml is provided; run pre-commit install to enforce both on every commit.

Related projects

genechart — a command-line tool (Rust) for rendering GEDCOM files as family-tree charts in text, SVG, or PDF (descendant, ancestor /pedigree fan, cascading, and boxed-couple layouts, with photos, highlights, and multi-page poster tiling). It complements gedinfo: once you've used gedinfo to find the individuals and relationships you care about, pass their IDs to genechart to produce a visual chart. Both read GEDCOM 5.5.1 and support custom GEDCOM tags via TOML.

License

Licensed under the MIT License — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 103 Commits
.github/workflows		.github/workflows
bin		bin
gedinfo		gedinfo
tests		tests
.git-blame-ignore-revs		.git-blame-ignore-revs
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

gedinfo

Installation

Running

Configuration

Commands

indi

name

id

names

males

females

nosex

noname

living

relatives

ancestors

descendants

lastnames

givennames

gen

relationship

fam

roots

leaves

disjoint

stat

tags

calendar

diff

anonymize

strip

explore (TUI mode)

Testing

Formatting & linting

Related projects

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages