GRAMPS(1)

📦
version 6.0.8 · 7 versions
, in fedora 43, fedora 44, nixpkgs unstable, ubuntu stonking

💖 GRAMPS(1) 💖

okay bestie, pull up a chair, because we're reading the GRAMPS(1) manual together and honestly? it's giving genealogy icon. this is the manual page for the one and only gramps — the Genealogical Research and Analysis Management Programming System. yes the acronym is a lot. we love her anyway. 🎀

✨ NAME ✨

gramps — Genealogical Research and Analysis Management Programming System.

no cap, that's the whole name. she's long but she's worth it. 💅

🦋 SYNOPSIS 🦋

gramps [-? | --help] [--usage] [--version] [-l] [-L] [-u |
--force-unlock] [-O | --open=DATABASE [-f | --format=FORMAT]] [-i |
--import=FILE [-f | --format=FORMAT]] [--remove=FAMILY_TREE_PATTERN] [-e
| --export=FILE [-f | --format=FORMAT]] [-a | --action=ACTION] [-p |
--options=OPTION-STRING]] [FILE] [--version]

look at all those flags. she's versatile. she contains multitudes. 🌈

🌸 DESCRIPTION 🌸

Gramps is a Free, Open Source genealogy program. it's written in Python, and it uses the GTK+/GNOME interface — so if you've touched a GNOME app before, you already know the vibe.

if you've ever used other genealogy programs like Family Tree Maker™, Personal Ancestral Files™, or the GNU Geneweb, Gramps is gonna feel familiar immediately. no learning curve, just vibes. 🫶

and the best part? it supports importing the ever-popular GEDCOM format, which is used worldwide by almost all other genealogy software. so yes, your data can come hang out here. it's giving open borders. ✨

👑 OPTIONS 👑

  • gramps FILE — when FILE is handed over (with no flags at all) as a family tree name or as a family tree database directory, Gramps opens it and starts an interactive session. but if FILE is a file format that Gramps understands, then it creates an empty family tree whose name is based on the FILE name, and imports the data into it. any other options? ignored, bestie. this launch style is perfect for using gramps as a handler for genealogical data in, like, web browsers. and this invocation can accept any data format native to gramps — see below. 💖
  • -f, --format=FORMAT — explicitly say what format the FILE is, for the -i or -e option that came right before it. if you don't give -f for some FILE, the format gets guessed from its extension or MIME type. iykyk. 🔍

formats available for export are gramps-xml (guessed if FILE ends with .gramps), gedcom (guessed if FILE ends with .ged), or any file export available through the Gramps plugin system.

formats available for import are gramps-xml, gedcom, gramps-pkg (guessed if FILE ends with .gpkg), and geneweb (guessed if FILE ends with .gw).

formats available for export are gramps-xml, gedcom, gramps-pkg, wft (guessed if FILE ends with .wft), geneweb.

  • -l — print a list of known family trees. cute, quick, done. 📋
  • -L — print a detailed list of known family trees. she said more. 🔥
  • -u, --force-unlock — unlock a locked database. (we've all been locked at some point. no judgement. 💀)
  • -O, --open=DATABASE — open DATABASE, which has to be an existing database directory or an existing family tree name. and if you give no action, import, or export options on the command line, then an interactive session starts using that database. main character energy. 👑
  • -i, --import=FILE — import data from FILE. if no database was specified, then an empty database is created, called Family Tree x (where x is an incrementing number). ✨

when more than one input file is given, each one has to be preceded by a -i flag. the files get imported in the order you specified, e.g. -i FILE1 -i FILE2 and -i FILE2 -i FILE1 might produce different gramps IDs in the resulting database. order matters, bestie. 🎀

  • -e, --export=FILE — export data into FILE. for gramps-xml, gedcom, wft, gramps-pkg, and geneweb, the FILE is the name of the resulting file. 💾

when more than one output file is given, each one has to be preceded by an -e flag. the files are written one by one, in the specified order.

  • -a, --action=ACTION — perform ACTION on the imported data. this happens after all imports are successfully completed. currently available actions are summary (same as Reports→View→Summary), check (same as Tools→Database Processing→Check and Repair), report (generates report), and tool (runs a plugin tool). both report and tool need the OPTION-STRING supplied by the -p flag. 🛠️

the OPTION-STRING should satisfy the following conditions:

  • it should not contain any spaces.
  • if some arguments need to include spaces, the string should be enclosed with quotation marks, following shell syntax.
  • the option string is a list of pairs with name and value (separated by an equals sign).
  • the name and value pairs must be separated by commas.

most of the report or tools options are specific for each report or tool. however, there are some common options. 👇

  • name=name — this mandatory option determines which report or tool will be run. if the supplied name does not correspond to any available report or tool, an error message will be printed followed by the list of available reports or tools (depending on the ACTION).
  • show=all — this will produce the list of names for all options available for a given report or tool.
  • show=optionname — this will print the description of the functionality supplied by optionname, as well as what are the acceptable types and values for this option.

use the above options to find out everything about a given report. 💅

when more than one output action is given, each has to be preceded by a -a flag. the actions are performed one by one, in the specified order.

  • -d, --debug=LOGGER_NAME — enable debug logs for development and testing. look at the source code for details. (go on, peek. 🙈)
  • --version — print the version number of gramps and then exit. bye bestie! 👋

🧚 OPERATION 🧚

if the first argument on the command line does not start with a dash (i.e., no flag), gramps will attempt to open the file with the name given by the first argument and start an interactive session, ignoring the rest of the command line arguments. yeah. she said what she said.

if the -O flag is given, then gramps will try opening the supplied database and then work with that data, as instructed by the further command line parameters.

with or without the -O flag, further imports, exports, and actions may be specified on the command line by using -i, -e, and -a flags.

the order of -i, -e, or -a options does not matter. the actual order they are processed is always: all imports (if any) → all actions (if any) → all exports (if any). but opening must always be first! 🚨

if no -O or -i option is given, gramps will launch its main window and start the usual interactive session with an empty database, since there is no data to process anyway. empty era. ✨

if no -e or -a options are given, gramps will launch its main window and start the usual interactive session with the database resulting from all imports. this database resides in the import_db.grdb under the ~/.gramps/import directory. 📁

any errors encountered during import, export, or action will be dumped either to stdout (if these are exceptions handled by gramps) or to stderr (if these are not handled). use usual shell redirections of stdout and stderr to save messages and errors to files. no cap, that's how you keep the receipts. 🧾

🌈 EXAMPLES 🌈

to open an existing family tree and import an xml file into it, one may type:

gramps -O 'My Family Tree' -i ~/db3.gramps

the above changes the opened family tree. to do the same, but import both in a temporary family tree and start an interactive session, one may type:

gramps -i 'My Family Tree' -i ~/db3.gramps

to import four databases (whose formats can be determined from their names) and then check the resulting database for errors, one may type:

gramps -i file1.ged -i file2.tgz -i ~/db3.gramps -i file4.wft -a check

to explicitly specify the formats in the above example, append filenames with appropriate -f options:

gramps -i file1.ged -f gedcom -i file2.tgz -f gramps-pkg \
-i ~/db3.gramps -f gramps-xml -i file4.wft -f wft -a check

to record the database resulting from all imports, supply a -e flag (use -f if the filename does not allow gramps to guess the format):

gramps -i file1.ged -i file2.tgz -e ~/new-package -f gramps-pkg

to import three databases and start an interactive gramps session with the result:

gramps -i file1.ged -i file2.tgz -i ~/db3.gramps

to run the Verify tool from the commandline and output the result to stdout:

gramps -O 'My Family Tree' -a tool -p name= verify

finally, to start a normal interactive session type:

gramps

see? she's flexible. she ate. 💅🔥

🌱 ENVIRONMENT VARIABLES 🌱

the program checks whether these environment variables are set:

  • LANG — describe which language to use. e.g., for the Polish language this variable has to be set to pl_PL.UTF-8. 🗣️
  • GRAMPSHOME — force Gramps to use the specified directory to keep program settings and databases in. by default, this variable is not set and gramps assumes that the folder with all databases and profile settings should be created within the user profile folder (described by environment variable HOME for Linux or USERPROFILE for Windows 2000/XP). 🏠

🫧 CONCEPTS 🫧

supports a python-based plugin system, allowing import and export writers, report generators, tools, and display filters to be added without modification of the main program. iconic behaviour, honestly.

in addition to generating direct printer output, report generators also target other output formats, such as LibreOffice, AbiWord, HTML, or LaTeX to allow the users to modify the format to suit their needs. 🎨

📂 FILES 📂

${PREFIX}/bin/gramps

${PREFIX}/lib/python3/dist-packages/gramps/

${PREFIX}/share/

${HOME}/.gramps

💜 AUTHORS 💜

Donald Allingham <don@gramps-project.org> https://www.gramps-project.org/

this man page was originally written by: Brandon L. Griffith <brandon@debian.org> for inclusion in the Debian GNU/Linux system.

this man page is currently maintained by: Gramps project <xxx@gramps-project.org>

📚 DOCUMENTATION 📚

the user documentation is available through a web browser in the form of the Gramps Manual.

the developer documentation can be found on the https://www.gramps-project.org/wiki/index.php/Portal:Developers portal. 🧭

and that's the whole page, bestie. every flag, every path, every ™, exactly where it belongs. nothing skipped, nothing invented. we simply made it ✨cuter✨.

this was the GRAMPS(1) manual page from the Gramps project, version 6.0.8. thanks for reading the whole thing with me — you're a real one. mwah. 🎀💖✨

📦 where this page comes from