Difference between revisions of "Gramps 3.3 Wiki Manual - Command Line"
m (1 revision)
Revision as of 10:29, 1 March 2011
This appendix provides the reference to the command line capabilities available when launching GRAMPS from the terminal.
|Special copyright notice: All edits to this page need to be under two different copyright licenses:
These licenses allow the Gramps project to maximally use this wiki manual as free content in future Gramps versions. If you do not agree with this dual license, then do not edit this page. You may only link to other pages within the wiki which fall only under the GFDL license via external links (using the syntax: [https://www.gramps-project.org/...]), not via internal links.
- 1 Available options
- 1.1 List options
- 1.2 Format options
- 1.3 Opening options
- 1.4 Import options
- 1.5 Export options
- 1.6 Action options
- 1.7 Force unlock option
- 1.8 Configuration (config) option (Gramps 3.3)
- 2 Operation
- 3 Examples
- 4 Environment variables
This section provides the reference list of all command line options available in GRAMPS. If you want to know more than just a list of options, see next sections: Operation and Examples. A list is also available on this page.
-l, print a list of known family trees -L, print a detailed list of known family trees
The format of any file destined for opening, importing, or exporting can be specified with the
option. The acceptable format values are listed below.
Full family tree support
These formats contain all your data that is present in a family tree.
- gramps - GRAMPS XML format: This format is available for import, and export. When not specified, it can be guessed if the filename ends with .gramps
- gpkg - GRAMPS package XML format: This format is available for import and export. When not specified, it can be guessed if the filename ends with .gpkg. This creates a zip package with your data as xml, and all your media files included
- grdb - pre GRAMPS 3.x database: This format is available for import to support the old file format of GRAMPS. Everything in the grdb file is imported. When not specified, it can be guessed if the filename ends with .grdb
- burn - GNOME iso burning: export, only available on GNOME where burn protocol exists
Reduced family tree support
These formats contain most, but not all data that can be created in GRAMPS
- ged - GEDCOM format: This format is available for import, and export. When not specified, it can be guessed if the filename ends with .ged
- gw - GeneWeb file: This format is available for import and export. When not specified, it can be guessed if the filename ends with .gw
Subset of your data
These formats contain a specific subset of your data
- csv - Comma Seperated Value: This format is available for import and export. Be carefull however, import must be as values created by the export function. Only a part of your data is contained in the output.
- vcf - VCard format: import and export
- vcs - VCalander format: export
- def - old Pro-Gen format: import
- wft - Web Family Tree: This format is available for export only. When not specified, it can be guessed if the filename ends with .wft
You can open a family tree, or you can open a file by importing it in an empty family tree. To let GRAMPS handle this automatically, just supply the familytree or filename you want to open:
python gramps.py 'My Fam Tree' python gramps.py JohnDoe.ged
The first opens a family tree, the second imports a gedcom into an empty family tree.
Additionally, you can pass GRAMPS the name of the family tree to be opened:
- use this option :
-O, Open of a family tree. This can be done also by just typing the name (name or database dir)
python gramps.py 'Family Tree 1' python gramps.py /home/cristina/.gramps/grampsdb/47320f3d python gramps.py -O 'Family Tree 1' python gramps.py -O /home/cristina/.gramps/grampsdb/47320f3d
If no option is given, just a name, GRAMPS will ignore the rest of the command line arguments. Use the -O flag to open, -i to import, and do something with the data.
Only family trees can be opened directly. For other formats, you will need to use the import option which will set up the empty database and then import data into it.
Only a single family tree can be opened. If you need to combine data from several sources, you will need to use the import option.
The files destined for import can be specified with the
option. The format can be specified with the
option, immediately following the filename . If not specified, the guess will be attempted based on the filename.
python gramps.py -i 'Family Tree 1' -i 'Family Tree 2' python gramps.py -i test.grdb -i data.gramps
More than one file can be imported in one command. If this is the case, GRAMPS will incorporate the data from the next file into the database available at the moment.
When more than one input file is given, each has to be preceded by
flag. The files are imported in the specified order, i.e.
-i file1 -i file2
-i file2 -i file1
might produce different GRAMPS IDs in the resulting database.
The files destined for export can be specified with the
option. The format can be specified with the
option immediately following the filename . If not specified, the guess will be attempted based on the filename . For iso format, the filename is actually the name of directory the GRAMPS database will be written into. For gramps-xml, gpkg, gedcom, wft, geneweb, and gramps-pkg, the filename is the name of the resulting file.
-e, export a family tree in required format. It is not possible to export to a family tree.
python gramps.py -i 'Family Tree 1' -i test.grdb -f grdb -e mergedDB.gramps
Note that above does not change 'Family Tree 1' as everything happens via a temporary database, whereas:
python gramps.py -O 'Family Tree 1' -i test.grdb -f grdb -e mergedDB.gramps
will import test.grdb into Family Tree 1, and then export to a file !
Exporting more files
More than one file can be exported in one command. If this is the case, GRAMPS will attempt to write several files using the data from the database available at the moment.
When more than one output file is given, each has to be preceded by
flag. The files are written one by one, in the specified order.
The action to perform on the imported data can be specified with the
option. This is done after all imports are successfully completed.
The following actions remain the same:
- report: This action allows producing reports from the command line.
- tool: This action allows to run a tool from the command line.
Reports and tools generally have many options of their own, so these actions should be followed by the report/tool option string. The string is given using the
The actions available in older versions of Gramps which were relocated in Gramps 3.3 are:
- summary: This action was the same as Reports ->View ->Summary . In Gramps 3.3 it was replaced by (or renamed to) -a report -p name=summary.
- check: This action was the same as Tools ->Database Processing ->Check and Repair . In Gramps 3.3 it was replaced by (or renamed to) -a tool -p name=check.
report action option
You can generate most reports from the command line using the report action. An example:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html"
In version 3.3, you can provide the css style to use here with the css option:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html,css=Web_Nebraska.css"
or without css in the html output:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html,css="
Most of the report options are specific for every report. However, there are some common options.
- name=report_name: This mandatory option determines which report will be generated. If the supplied report_name does not correspond to any available report, the error message will be printed followed by the list of available reports.
- of : output filename
- off: output format. These are the extension an output format makes available, eg, pdf, html, doc, ...
- style: for text reports, the stylesheet to use. Defaults to 'default'.
- show=all: This will produce the list of names for all options available for a given report.
- show=option_name: This will print the description of the functionality supplied by the option_name, as well as what are the acceptable types and values for this option.
So, to learn to use a report, do for example:
gramps -O "Family Tree 1" -a report -p "name=family_group,show=all"
If an option is not supplied, the last used value will be used. If this report has never been generated before, then the value from last generated report will be used when applicable. Otherwise, the default value will be used.
When more than one output action is given, each has to be preceded by
flag. The actions are performed one by one, in the specified order.
Force unlock option
-u, you can extend the -O flag with -u to force a locked family to be unlocked. This allows to recover from a crash that leaves the famlily tree locked from the command line.
Note that it is not possible to open family trees that need repair from the command line
Configuration (config) option (Gramps 3.3)
The option takes three forms: (the following examples use behavior.database-path as the configuration variable to change.)
1) See all config values
2) See a value:
3) Set a value:
3.1) Set a value to its default:
If the first argument on the command line does not start with dash (i.e. no flag), GRAMPS will attempt to open the file with the name given by the first argument and start interactive session, ignoring the rest of the command line arguments.
flag is given, then GRAMPS will try opening the supplied file name and then work with that data, as instructed by the further command line parameters.
Only one file can be opened in a single invocation of GRAMPS. If you need to get data from multiple sources, use the importing options by using
With or without the
flag, there could be multiple imports, exports, and actions specified further on the command line by using
flags. The order of
options with respect to each does not matter. The actual execution order always is: all imports (if any) -> all exports (if any) -> all actions (if any).
But opening must always be first!
option is given, GRAMPS will launch its main window and start the usual interactive session with the empty database, since there is no data to process, anyway. If no
options are given, GRAMPS will launch its main window and start the usual interactive session with the database resulted from opening and all imports (if any). This database resides in the import_db.grdb file under the ~/.gramps/import/ directory.
Any errors encountered during import, export, or action, will be either dumped 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 in files.
- 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.gpkg -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.gpkg -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 -e flag (use -f if the filename does not allow GRAMPS to guess the format):
gramps -i file1.ged -i file2.gpkg -e ~/new-package -f gramps-pkg
- To save any error messages of the above example into files outfile and errfile, run:
gramps -i file1.ged -i file2.dpkg -e ~/new-package -f gramps-pkg >outfile 2>errfile
- To import three databases and start interactive GRAMPS session with the result:
gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps
- To open a database and, based on that data, generate timeline report in PDF format putting the output into the my_timeline.pdf file:
gramps -O 'Family Tree 1' -a report -p name=timeline,off=pdf,of=my_timeline.pdf
- To convert a grdb on the fly to a .gramps xml file:
gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml
- To generate a web site into an other locale (in german):
LANGUAGE=de_DE; LANG=de_DE.UTF-8 gramps -O 'Family Tree 1' -a report -p name=navwebpage,target=/../de
- Finally, to start normal interactive session type:
GRAMPS can take advantage of these environment variables (but do not change them if you do not know what are you doing):
- GRAMPSHOME - if set, override default path to profile allowing user to use ex. network drive to store data and all settings.
- LANG - is used by GRAMPS to determine which language file should be loaded.