Changes

Jump to: navigation, search

Gramps 4.1 Wiki Manual - Command Line

3,931 bytes added, 22:02, 5 February 2016
m
Protected "Gramps 4.1 Wiki Manual - Command Line": outdated user manual ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))
=== MS Windows ===
MS Windows is a [[Download#Comunity_supported|community supported]] platform. If you install the [[All_In_One_Gramps_Software_Bundle_for_Windows|Windows AIO]] GrampsAIO32 or GrampsAIO64 executable, then this will place an icon on the desktop as well as a menu iten in the 'Start' menu.
What is the best way of knowing what command to type?
=== Mac OS X ===
Mac OS X is a [[Download#Comunity_supported|community supported]] platform. If you download the Mac OS X disk image (.dmg), then you simply drag the application to your application folder (or anywhere else you want to store it) and start Gramps by double clicking on the application in the normal way.
To run from the command line, you'll need to start Terminal, found in Applications:Utilities.
The '''python options''' that you may come across are:
* <code>-E </code> Ignore all PYTHON* environment variables, e.g. <code>PYTHONPATH </code> and <code>PYTHONHOME</code>, that might be set.* <code>-O </code> Turn on basic optimizations. This changes the filename extension for compiled (bytecode) files from <code>.pyc </code> to <code>.pyo</code>. See also PYTHONOPTIMIZE.
The <code>-O </code> optimise flag has a number of effects in Gramps:
* If it is not turned on, an additional '''Debug''' entry appears in the '''Tools''' menu.
* If it is not turned on, [[Logging_system#So_how_logging_works_in_Gramps_after_all.3F|info logging messages are output]].
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|Operation]] and [[#Examples| Examples]]. The summary below is printed by
gramps -h.or gramps --help
Usage: gramps.py [OPTION...] --load-modules=MODULE1,MODULE2,... Dynamic modules to load Help options -?, --help Show this help message --usage Display brief usage message Application options -O, --open=FAMILY_TREE Open Family Tree -C, --create=FAMILY_TREE Create on open if new Family Tree -i, --import=FILENAME Import file -e, --export=FILENAME Export file -f, --format=FORMAT Specify Family Tree format -a, --action=ACTION Specify action -p, --options=OPTIONS_STRING Specify options -d, --debug=LOGGER_NAME Enable debug logs -l List Family Trees -L List Family Trees in Detail -t List Family Trees, tab delimited -u, --force-unlock Force unlock of Family Tree -s, --show Show config settings -c, --config=[config.setting[:value]] Set config setting(s) and start Gramps -y, --yes Don't ask to confirm dangerous actions (non-GUI mode only) -q, --quiet Suppress progress indication output (non-GUI mode only) -v, --version Show versions
The usage message is as follows:
2. 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 tool -p name=check.
3. To record the database resulting from all imports, supply -e flag
6. 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
7. To generate a summary of a database:
gramps -O 'Family Tree 1' -a report -p name=summary
8. Listing report options
To learn about available report names, use name=show string.
9. To convert a family tree Family Tree on the fly to a .gramps xml file:
gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml
python gramps.py JohnDoe.ged
The first opens a family tree, the second imports a gedcom GEDCOM into an empty family tree.
Additionally, you can pass Gramps the name of the family tree to be opened:
* use this option : <precode>-O famtree</precode> or <precode>--open=famtree </precode>
<code>-O</code>, Open of a family tree. This can be done also by just typing the name (name or database dir)
Examples:
{{Man tip| Tip |If no option is given, just a name, Gramps will ignore the rest of the command line arguments. Use the <code>-O </code> flag to open, <code>-i </code> to import, and do something with the data.}}
{{Man tip| Tip |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.}}
=== Import options ===
The files destined for import can be specified with the <precode>-i filename</precode> or <precode>--import=filename</precode> option. The format can be specified with the <precode>-f format</precode> or <precode>--format=format</precode> option, immediately following the ''filename'' . If not specified, the guess will be attempted based on the ''filename''.
Example:
{{man tip | Tip |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 <precode>-i</precode> flag. The files are imported in the specified order, i.e. <precode> -i file1 -i file2 </precode> and <precode> -i file2 -i file1 </precode> might produce different GRAMPS Gramps IDs in the resulting database.
=== Export options ===
The files destined for export can be specified with the <precode>-e filename</precode> or <precode>--export=filename</precode> option. The format can be specified with the <precode>-f</precode> 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.
{{man tip| 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 <precode>-e</precode> flag. The files are written one by one, in the specified order.
=== Action options ===
The action to perform on the imported data can be specified with the <precode>-a action</precode> or <precode>--action=action</precode> option. This is done after all imports are successfully completed.
The following actions remain the same:
*''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 <precode>-p option_string</precode> or <precode>--options=option_string</precode> option.
The actions available in older versions of Gramps which were relocated in Gramps 3.3 are:
gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html,css="
{{man tip| Report option string |The report option string should satisfy the following conditions: <br />It must not contain any spaces (due to the general nature of the command line interface). If some arguments need to include spaces, the string should be enclosed with quotation marks.<br />Option string must list pairs of option names and values.Within a pair, option name and value must be separated by the equal sign.<br />Different pairs must be separated by commas.}}
Most of the report options are specific for every report. However, there are some common options.
*<code>name=report_name</code>: This mandatory option determines which report will be generated. {{man note|Report names|If the supplied report_name does not correspond to any available report, an error message will be printed followed by the this list of available reports.<br /><pre> Available names are: ancestor_chart - Ancestor Tree ancestor_report - Ahnentafel Report birthday_report - Birthday and Anniversary Report calendar - Calendar descend_chart - Descendant Tree descend_report - Descendant Report det_ancestor_report - Detailed Ancestral Report det_descendant_report - Detailed Descendant Report endofline_report - End of Line Report family_descend_chart - Family Descendant Tree family_group - Family Group Report familylines_graph - Family Lines Graph fan_chart - Fan Chart hourglass_graph - Hourglass Graph indiv_complete - Complete Individual Report kinship_report - Kinship Report navwebpage - Narrated Web Site notelinkreport - Note Link Report number_of_ancestors - Number of Ancestors Report place_report - Place Report records - Records Report rel_graph - Relationship Graph statistics_chart - Statistics Charts summary - Database Summary Report tag_report - Tag Report timeline - Timeline Chart WebCal - Web Calendar</pre>}}*<code>of </code>: output filename*<code>off</code>: output format. These are the extension an output format makes available, eg, pdf, html, doc, ...*<code>style</code>: for text reports, the stylesheet to use. Defaults to 'default'.*<code>show=all</code>: This will produce the list of names for all options available for a given report.*<code>show=option_name</code>: 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:
{{man tip| Tip |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 <precode>-a</precode> flag. The actions are performed one by one, in the specified order.
{{man tip| lists |Some reports have options or arguments which are interpreted (by the report) to be on multiple lines. For instance some reports allow you to format how the information will be shown, perhaps with a name on one line and the person's birth date on the next line. Such multiple-line options or arguments are called "lists" by Gramps.}}
On the command line such lists must always start with a left square bracket<precode>[</precode>and must always end with a right square bracket<precode>]</precode>but since such square brackets are usually "special" to the "shell" (they mean something to the command interpreter
you are typing the command to), you must "escape" them so that they are ignored by your shell.
The details vary with each shell but (in linux/UNIX) usually you can precede such a square bracket with a backslash<precode>\</precode>or put quotation marks around the square bracket, usually either "single" or "double" ones.
The Hourglass Graph report allows you to put a "note" at the top of the report and such a "note" is an example of a "list" option. Here is an example:
gramps -O "Family Tree 1" -a tool -p name=verify
{{man note|Tool names|If the supplied tool_name does not correspond to any available tool, an error message will be printed followed by this list of available tools.<br /><pre> Available names are: check - Check and Repair Database chtype - Rename Event Types dgenstats - Dump Gender Statistics evname - Extract Event Description populatesources - Populate Sources and Citations rebuild - Rebuild Secondary Indexes rebuild_genstats - Rebuild Gender Statistics rebuild_refmap - Rebuild Reference Maps reorder_ids - Reorder Gramps IDs test_for_date_parser_and_displayer - Check Localized Date Displayer and Parser testcasegenerator - Generate Testcases for Persons and Families verify - Verify the Data</pre>}} ==== book action option (new ===={{man note|New feature|Added in Gramps 4.1) ====}}
You can run books from the command line using the 'book' action.
To see which ones, say:
To run a book, for instance a book called "mybook":
gramps -O "Family Tree 1" -a book -p name=mybook
 
{{man note|Book names|If the supplied book_name does not correspond to any available Book, an error message will be printed followed by this list of available Books. eg: Example listing only as the Books will be whatever you have named them.<br />
<pre>
Available names are:
Granny Jones
Grampa John
Smith Family History
</pre>}}
=== Force unlock option ===
*<code>-u, </code>: you can extend the <code>-O </code> flag with <code>-u </code> to force a locked family to be unlocked. This allows you to recover from a crash that leaves the family tree (database) locked, from the command line.
An example (to unlock the "Family Tree 1" database):
:<code>gramps -O "Family Tree 1" -a report -u > /dev/null</code>
{{man note|Note that it |It is not possible to open family trees that need repair from the command line.}}
=== Configuration (config) option ===
The option takes three forms:(the following examples, except 3.2, use behavior.database-path as the When all configuration variable to change(s) are set Gramps will start with these new values.)
These options can takes three forms:{{man note|Note|Except for examples <tt>1) See all config values</tt> and <tt>3.2</tt>, All the following examples, use <code>behavior.database-path</code> as the configuration variable to change.}}
1) See all config values: <code>-s </code> or <code>--show</code><br>For example:<pre>$python gramps.py -showGramps config settings from /home/username/.gramps/gramps41/gramps.ini:behavior.max-age-prob-alive=110behavior.betawarn=falsebehavior.check-for-updates=0behavior.check-for-update-types=['new']behavior.avg-generation-gap=20behavior.database-path='/home/grampsdev/.gramps/grampsdb'behavior.startup=0behavior.database-backend='bsddb'</pre>
[[Image:CommandLineExampleOutput-s-40.png|400px|thumb|right|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Command Line Example Output for ''python gramps.py -s'']]
{{-}}
2) See a value:<code>--config=behavior.database-path</code> or <code>-c behavior.database-path</code><br>For example:<pre>$python gramps.py --config=behavior.database-pathCurrent Gramps config setting: behavior.database-path:'/home/username/.gramps/grampsdb'</pre>
3) Set a value: <code>--config=behavior.database-path :'/media/mydb'</code> or <code>-c behavior.database-path:'/media/mydb'</code><br>For example:
3.1) Set a valueto its default: <code>--config=behavior.database-path:DEFAULT</code> or <code>-c behavior.database-path:DEFAULT</code><br>For example:
--config=behavior.database-path:'/media/mydb' or -c behavior.database-path:'/media/mydb' 3.1) Set a value to its default:  --config=behavior.database-path:DEFAULT or -c behavior.database-path:DEFAULT 3.2) Set more than one value:  <code>--config=behavior.use-tips:False --config=behavior.autoload:True </code> or <code>-c behavior.use-tips:False -c behavior.autoload:True</code> When all configuration variable(s) are set Gramps will start with these new values.<br>For example:
== 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.
If the <precode>-O</precode> 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.
{{man note|1=Note |2=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 <precode>-i</precode> flag.}}
With or without the <precode>-O</precode> flag, there could be multiple imports, exports, and actions specified further on the command line by using <precode>-i</precode> , <precode>-e</precode> , and <precode>-a</precode> flags.
The order of <precode>-i</precode> , <precode>-e</precode> , or <precode>-a</precode> 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).
{{man note| Note |But opening must always be first!}}
If no <precode>-O</precode> or <precode>-i</precode> 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. (Unless you have already expressed a "preference" that it start with the last database it used.)
If no <precode>-e</precode> or <precode>-a</precode> 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 a directory under the ''<code>~/.gramps/importgrampsdb/</code>'' 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:
:<precode>gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps -i file4.wft -a check</precode>
*To explicitly specify the formats in the above example, append filenames with appropriate -f options:
:<precode>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</precode>
*To record the database resulting from all imports, supply -e flag (use -f if the filename does not allow Gramps to guess the format):
:<precode>gramps -i file1.ged -i file2.gpkg -e ~/new-package -f gramps-pkg</precode>
*To save any error messages of the above example into files outfile and errfile, run:
:<precode>gramps -i file1.ged -i file2.dpkg -e ~/new-package -f gramps-pkg >outfile 2>errfile </precode>
*To import three databases and start interactive Gramps session with the result:
:<precode>gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps </precode>
*To open a database and, based on that data, generate timeline report in PDF format putting the output into the my_timeline.pdf file:
:<precode>gramps -O 'Family Tree 1' -a report -p name=timeline,off=pdf,of=my_timeline.pdf </precode>
{{man tip|1=Listing report options |2=Use the <ttcode>''name=timeline,show=all''</ttcode> to find out about all available options for the timeline report. To find out details of a particular option, use <ttcode>''show=option_name''</ttcode> , e.g. <ttcode>''name=timeline,show=off''</ttcode> string. To learn about available report names, use <ttcode>''name=show''</ttcode> string.}}
*To convert the bsddb database on the fly to a .gramps xml file:
:<precode>gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml</precode>
* To generate a web site into an other locale (in german):
:<precode>LANGUAGE=de_DE; LANG=de_DE.UTF-8 gramps -O 'Family Tree 1' -a report -p name=navwebpage,target=/../de </precode>
*Finally, to start normal interactive session type:
:<precode>gramps</precode>
== Environment variables==
{{man warn|Warning|Gramps can take advantage of these the following environment variables <br />('''but do not Only change them if you do not know what are you doing.'''):}}
===GRAMPSHOME===
* '''LANG''' - is used by Gramps to determine which language file should be loaded.
{{man note|MacOSX|Because of the way launching with Finder works, the environment variables for the Gramps.app bundle are hard-coded in <code>Gramps.app/Contents/MacOS/Gramps</code>. If for some reason you need to change them, edit that file with TextEdit; be sure to save it back as plain text. See as well [[Run_GRAMPS_in_another_locale#Change_Mac_OS_X_application_defaults|setting locale]] for an alternative to using the '''LANG''' and '''LANGUAGE''' environment variables.}}
===GRAMPSI18N===
* [[Translating_Gramps#.24GRAMPSI18N_.28for_your_locale.29| $GRAMPSI18N (for your locale) ]] - The LANG assumes the Gramps translations are installed globally. If this is not the case, you need to give Gramps the directory where the translations will be found. A translation is called <code>gramps.mo</code>, you can find it in linux with the locate command. For example, if you have Swedish in directory <code>/home/me/gramps/mo/sv/gramps.mo</code>, you can direct Gramps there using:
GRAMPSI18N=/home/me/gramps/mo LC_ALL=C.UTF-8 LANG="sv" python3 gramps

Navigation menu