Charted Roots supports importing and exporting family data in GEDCOM, Gramps XML, and CSV formats through guided step-by-step wizards.

• Import/Export Hub
  • Opening the Hub
  • Import Wizard
  • Export Wizard
• GEDCOM Import/Export
  • Importing a GEDCOM File
  • After Import
  • Duplicate Handling
  • Exporting to GEDCOM
  • Privacy Protection for Export
• Gramps XML Import
  • Supported File Formats
  • Importing a Gramps File
  • What Gets Created
  • Place Linking
  • Supported Event Types
  • Notes Import
  • Create Note Modal
  • Limitations
• CSV Import/Export
  • Importing from CSV/TSV
  • Exporting to CSV
  • Format Comparison
• Selective Branch Export

The Import/Export Hub provides a centralized entry point for all data import and export operations through guided wizards.

The hub displays two cards:

• Import — Launch the 7-step import wizard
• Export — Launch the 6-step export wizard

The import wizard guides you through 7 steps:

Key Features:

• Dynamic blocks toggle — Enable or disable dynamic content blocks in imported notes
• Integrated numbering — Apply reference numbers immediately after import without leaving the wizard
• Gramps media extraction — .gpkg packages automatically extract embedded media files

The export wizard guides you through 6 steps:

Privacy Controls:

• Exclude living persons — Completely omit people without death dates born after threshold year
• Redact living persons — Include structure but replace personal details with "[Living]"
• Birth year threshold — Configure how recent a birth date triggers living person protection

Entity Inclusions:

Toggle which entity types to include in the export:

• Sources and citations
• Places with hierarchy
• Notes and annotations

Charted Roots provides full round-trip support for GEDCOM 5.5.1 format, allowing you to import family trees from popular genealogy software and export your Obsidian data back to GEDCOM format.

Using the Import Wizard:

1. Open the Import/Export Hub (see Opening the Hub)
2. Click the Import card
3. Select GEDCOM 5.5.1 format
4. Drag and drop your .ged file or click to browse
5. Configure import options:
   • Entity types — People, events, sources, places (toggle each on/off)
   • Target folder — Where to create notes
   • Conflict handling — Skip, overwrite, or merge duplicates
   • Dynamic blocks — Enable/disable dynamic content blocks
6. Review the preview showing entity counts and any warnings
7. Click Import to begin
8. Optionally apply reference numbering in Step 6
9. Review summary and use quick actions to open imported notes

Data Quality Preview:

Before any files are created, Charted Roots analyzes the GEDCOM data and shows a quality preview modal if issues or place name variants are detected. This allows you to:

• Review detected issues organized by category:

  • Dates: Death before birth, future dates, events before birth/after death
  • Relationships: Gender/role mismatches, parent younger than child
  • References: Orphan references to non-existent records
  • Data: Missing names, unknown sex, no dates recorded

• Standardize place name variants before import:

  • Choose canonical forms for country names (e.g., "USA" vs "United States of America")
  • Standardize state abbreviations (e.g., "CA" vs "California")
  • Your choices affect both file names and frontmatter property values

• Decide how to proceed:

  • Click "Proceed with import" to apply your choices and continue
  • Click "Cancel" to abort without creating any files

This preview step ensures consistent data from the start, avoiding cleanup work after import.

Progress Indicator:

During import, a modal shows:

• Current phase (validating, parsing, places, sources, people, relationships, events)
• Progress bar with current/total count
• Running statistics (places, sources, people, events created)

What Gets Created:

Supported GEDCOM Tags:

Individuals:

• INDI - Individuals → person notes
• NAME - Person names
• BIRT/DEAT - Birth and death → event notes
• DATE - Event dates (qualifiers ABT, BEF, AFT, CAL, EST, and BET...AND ranges are preserved)
• PLAC - Event locations → place wikilinks
• FAMC/FAMS - Family relationships
• SEX - Gender
• _UUID - Preserved as cr_id
• Xref IDs (e.g., @I0001@) → external_id for round-trip export support

Events (create event notes):

• Core: BIRT, DEAT, MARR, DIV
• Life Events: BURI, CREM, ADOP, GRAD, RETI, CENS
• Career/Residence: RESI, OCCU, EDUC
• Legal/Estate: PROB, WILL, NATU, MILI
• Migration: IMMI, EMIG
• Religious: BAPM, CHR, CHRA, CONF, FCOM, ORDN, BARM, BASM, BLES
• Family: ENGA, MARB, MARC, MARL, MARS, ANUL, DIVF

Person Attributes (stored as properties):

• DSCR → physicalDescription
• IDNO → identityNumber
• NATI → nationality
• RELI → religion
• TITL → title
• PROP → property
• CAST → caste
• NCHI → childrenCount
• NMR → marriageCount
• SSN → ssn (automatically redacted from exports)
• _RESEARCH_LEVEL → research_level (custom tag, 0-6 research progress level)

Sources:

• SOUR - Source records → source notes
• TITL - Source title
• AUTH - Author
• PUBL - Publication info
• REPO - Repository

Marriage Metadata (Enhanced Spouse Support):

• MARR - Marriage events → spouse1_marriage_date
• DIV - Divorce events → spouse1_divorce_date
• PLAC - Marriage locations → spouse1_marriage_location

Media Import (OBJE Records):

GEDCOM media object (OBJE) records can be imported to link photos, documents, and scans to person, event, and source notes.

Enabling Media Import:

1. In the import wizard Options step, enable Media references
2. If your GEDCOM contains absolute paths (e.g., /media/pictures/Ancestors/photo.jpg), optionally set a Path prefix to strip to convert them to vault-relative paths

What Gets Imported:

• Top-level 0 @Oxxxx@ OBJE record definitions
• 1 OBJE @Oxxxx@ references on individuals, families, sources, and events
• Inline OBJE records with embedded FILE paths
• Media titles (TITL tags) are preserved for reference

Path Resolution:

Import Wizard Preview:

Before import, the wizard shows a live preview of how GEDCOM paths will be converted to wikilinks. This helps you verify the path prefix setting is correct.

Vault Validation:

After import, Charted Roots validates that referenced media files exist in your vault. A notification reports any missing files, allowing you to copy them to your media folder.

Frontmatter Output:

media:
  - "[[photo1.jpg]]"
  - "[[document.pdf]]"

💡 Tip: If your media is stored in an external folder, consider using Obsidian's symlink support to link that folder into your vault's media directory.

1. Wait for sync completion - If bidirectional sync is enabled, Charted Roots automatically processes all imported relationships. Progress notifications show sync status.
2. Review imported notes in your configured folders (People, Events, Sources, Places)
3. Add research notes below the frontmatter in each file
4. Generate tree using Control Center → Tree Generation

Person Notes: If you import the same GEDCOM multiple times:

• Existing cr_id values are preserved
• Relationships are updated (not duplicated)
• New individuals are added
• Warnings appear for conflicts

Place Notes: Place duplicate detection uses multiple strategies:

• Primary: Case-insensitive match on full_name property
• Fallback: Match by title + parent combination (for places with same name in different regions)
• Existing places are updated (missing parent links added) rather than duplicated

State Abbreviation Normalization: US state abbreviations are automatically expanded to full names during import:

• Comma-separated: Abbeville, SC, USA → Abbeville, South Carolina, USA
• Space-separated: Abbeville SC → Abbeville, South Carolina

This prevents duplicate place notes from being created when GEDCOM data contains inconsistent state formats. All 50 US states plus DC are supported.

Place Type Inference: When importing places, Charted Roots uses context-aware type inference:

• Administrative division suffixes (County, Parish, Township, etc.) are detected
• When both "Abbeville" and "Abbeville County" exist as siblings, the non-suffixed version is inferred as a city/town rather than a county

Export your family data back to GEDCOM format for sharing with other genealogy software or family members.

Using the Export Wizard:

1. Open the Import/Export Hub (see Opening the Hub)
2. Click the Export card
3. Select GEDCOM 5.5.1 format
4. Choose folders:
   • Preference folders — Uses paths configured in Preferences
   • Specify folders — Select custom folders for each entity type
5. Configure privacy and inclusion options
6. Review the preview showing entity counts and privacy summary
7. Click Export to generate the file
8. Download or save the exported .ged file

Using Context Menu (Quick Export):

1. Right-click on a folder containing person notes
2. Select Export folder to GEDCOM
3. Choose export options
4. Save the .ged file

What Gets Exported:

• All person notes in the selected folder
• Relationships (parents, spouses, children)
• Birth and death dates/places
• Burial date and place
• Cause of death
• Marriage metadata (dates, locations, divorce dates) on FAM records
• Marriage variants (banns, contract, license, settlement) and divorce filed events
• Name components: prefix (NPFX), suffix (NSFX), surname prefix (SPFX), nickname (NICK)
• Person attributes: title, religion, nationality, physical description, ID number, property, caste, children count, marriage count, SSN
• Occupation (inline value)
• Age at event (AGE sub-tag)
• Date ranges (FROM/TO and BET/AND)
• Adult christening (CHRA) and standard christening (CHR) events
• Citation metadata: PAGE and QUAY sub-tags on SOUR references (from citation notes)
• cr_id values preserved as _UUID tags
• group_name values preserved as collection codes
• research_level preserved as _RESEARCH_LEVEL custom tag (0-6)
• Original GEDCOM xref IDs (if imported from GEDCOM) for round-trip support

Charted Roots includes optional privacy controls for protecting living persons in GEDCOM exports:

Enable Privacy Protection:

1. Go to Settings → Charted Roots → GEDCOM section
2. Enable "Privacy protection for living persons"
3. Configure the birth year threshold (default: 100 years ago)

Privacy Options:

• Exclude living persons: Completely remove potentially living people from export
• Anonymize living persons: Include structure but replace PII with "[Living]"

How Living Status is Determined:

• People without death dates AND born after the threshold year are considered potentially living
• Threshold is configurable (e.g., born after 1925 = potentially living)
• Family structure is maintained even when details are anonymized

Use Cases:

• Share family trees publicly without exposing living relatives' data
• Comply with genealogical privacy best practices
• Create "public" and "private" versions of your research

Export your family data to Gramps XML format (.gramps) for use with the Gramps desktop application. Available in the Export Wizard alongside GEDCOM.

What Gets Exported:

• All person notes with relationships, dates, and places
• Events linked to persons with source references
• Source records
• Places with hierarchy
• Citation metadata: spage and confidence elements on sourceref tags (from citation notes)

Charted Roots supports importing family data from Gramps, a popular open-source genealogy application.

• .gpkg - Gramps Package (recommended) — bundles XML data with media files
• .gramps - Native Gramps compressed format (gzip-compressed XML)
• .xml - Uncompressed Gramps XML export

💡 Tip: Export from Gramps as .gpkg to include media files (photos, documents, scans). Charted Roots will extract them to your vault automatically.

Using the Import Wizard:

1. Open the Import/Export Hub (see Opening the Hub)
2. Click the Import card
3. Select Gramps XML format (note: ".gpkg includes media")
4. Drag and drop your .gpkg, .gramps, or .xml file
5. Configure import options:
   • Entity types — People, events, sources, places (toggle each on/off)
   • Target folder — Where to create notes
   • Dynamic blocks — Enable/disable dynamic content blocks
6. Review the preview showing entity counts and media files
7. Click Import to begin (media files are automatically extracted from .gpkg)
8. Optionally apply reference numbering
9. Review summary and use quick actions

When you enable "Create place notes", Charted Roots:

1. Creates place notes first
2. Automatically converts birth/death places in person notes to wikilinks
3. Links event notes to place notes as well

This creates a fully connected web of notes where you can navigate between people, events, and places.

Gramps events are mapped to Charted Roots event types:

Events not in this list are imported as "custom" type.

Gramps person attributes are imported when present:

The Research Level attribute is automatically recognized from Gramps person records and imported as the research_level property. See Research Level for details on the 0-6 scale.

Notes attached to entities in Gramps can be imported in two ways:

1. Embedded notes (default) — Notes are appended to the corresponding entity note as a "## Notes" section
2. Separate note files (opt-in) — Notes are created as standalone files in a dedicated Notes folder with wikilinks from the entity

The import wizard includes two toggles for notes:

• Notes — Enable/disable notes import entirely (enabled by default)
• Create separate note files — When enabled, creates standalone note files instead of embedding (disabled by default)

Embedded notes (default behavior):

Separate note files:

When "Create separate note files" is enabled:

Separate note files include:

• cr_type: note — Identifies as a note entity
• cr_id — Unique identifier for sync support
• gramps_id / gramps_handle — Original Gramps identifiers for round-tripping
• cr_note_type — Note type from Gramps (Research, Person Note, Transcript, etc.)
• private: true — When the Gramps note has the privacy flag set

This approach is recommended when:

• You want to maintain notes as separate, reusable research documents
• Multiple entities share the same research note
• You plan to export data back to Gramps (preserves note identity)

Note formatting:

Gramps note styling is converted to Markdown:

Note format handling:

• Flowed notes (default): Normal text, rendered as regular Markdown
• Formatted notes (preformatted): Wrapped in code fences to preserve whitespace

Note types:

Each note's type from Gramps (e.g., "Person Note", "Research", "Source text") becomes a ### Heading in the imported content, making it easy to distinguish different types of notes on the same entity.

Privacy handling:

If any note attached to an entity has the privacy flag set in Gramps (priv="1"), the imported Obsidian note will include private: true in its frontmatter. This allows you to filter or exclude private data when exporting.

In addition to importing notes from Gramps, you can manually create note entities using the Create Note modal.

Opening the Create Note Modal:

Create Note Form:

Linking Entities:

Click "Add entity" to open a dropdown menu with entity type options:

• Person — Opens person picker to search and select people
• Event — Opens event picker to search and select events
• Place — Opens place picker to search and select places
• Source — Opens source picker to search and select sources

Selected entities appear as chips with remove buttons. These become wikilinks in the note's linked_entities frontmatter property.

Note File Structure:

---
cr_type: note
cr_id: note_abc123
cr_note_type: Research
linked_entities:
  - "[[John Smith]]"
  - "[[1850 Census]]"
---

Your note content here...

Gramps place types are preserved and mapped to Charted Roots place types:

• Administrative: country, state, province, county, region, district, borough, municipality
• Populated: city, town, village, parish, neighborhood
• Specific: cemetery, church, building, farm, street, address

1. Review imported notes in your configured folders
2. Add research notes below the frontmatter in each file
3. Generate tree using Control Center → Tree Generation

When importing a .gpkg package file, Charted Roots:

1. Extracts media files to your configured media folder
2. Links media to entities — Photos, documents, and scans attached in Gramps are linked to the corresponding person, event, place, or source notes via the media frontmatter property
3. Preserves order — The first media item serves as the thumbnail (matching Gramps convention)

Media extracted from Gramps packages can be viewed using the Media Gallery dynamic block.

• Repositories: Repository records create properties on sources but not separate notes

Charted Roots supports CSV and TSV file formats for easy data exchange with spreadsheets and other applications.

Using the Import Wizard:

1. Open the Import/Export Hub (see Opening the Hub)
2. Click the Import card
3. Select CSV format
4. Drag and drop your .csv or .tsv file
5. Review the auto-detected column mapping and adjust if needed
6. Configure target folder and options
7. Review the preview
8. Click Import to create notes

Auto-Detected Column Mapping:

Charted Roots automatically detects common column names and maps them to person properties:

You can manually adjust any mapping before importing if the auto-detection doesn't match your file's column names.

What Happens:

• Creates one Markdown note per row
• Generates cr_id for each person automatically
• Creates relationship links when parent/spouse columns reference other people in the file
• Supports both wikilink format ([[Name]]) and plain text names

Using the Export Wizard:

1. Open the Import/Export Hub (see Opening the Hub)
2. Click the Export card
3. Select CSV format (coming soon)
4. Choose folders to export from
5. Configure columns to include
6. Enable privacy protection if needed
7. Review and export

Note: CSV export via the wizard is planned for a future release. Currently available via context menu on folders.

Configurable Columns:

Choose which fields to include in your export:

• Core fields: name, cr_id, gender
• Dates: born, died
• Relationships: father, mother, spouse, children
• Metadata: collection, group_name, lineage

Privacy Protection:

Same privacy options as GEDCOM export:

• Exclude living persons entirely
• Anonymize living persons (replace PII with "[Living]")
• Configurable birth year threshold

Export specific portions of your family tree rather than the entire dataset. Available for both GEDCOM and CSV formats.

Ancestors Only: Export only the ancestors (parents, grandparents, etc.) of a selected person.

• Useful for pedigree charts
• Creates focused lineage documentation
• Reduces file size for large trees

Descendants Only: Export only the descendants (children, grandchildren, etc.) of a selected person.

• Useful for descendant reports
• Can optionally include spouses of descendants
• Great for sharing a specific family branch

Using the Export Wizard:

1. Open the Import/Export Hub and click Export
2. Select your format (GEDCOM 5.5.1)
3. In the Folders step, select "Branch export" mode
4. Choose a root person for the branch
5. Select branch type (ancestors or descendants)
6. Optionally enable "Include spouses" for descendant exports
7. Complete the remaining wizard steps

Selective branch export works together with collection filtering for precise exports:

1. Filter by collection to narrow the scope
2. Then apply branch selection to further refine
3. Result includes only people matching both criteria

Example workflow:

• Filter to "Maternal Line" collection
• Select branch: descendants of "Great-Grandmother Jane"
• Export only that specific branch within the maternal line

When exporting descendants, you can optionally include spouses:

• Enabled: Includes spouses of each descendant (helps show family units)
• Disabled: Exports only direct blood descendants

This option is particularly useful when you want complete family units rather than just the bloodline.