Changes

Jump to: navigation, search

Gramps 3.3 Wiki Manual - Command Line

3,789 bytes added, 13:00, 26 October 2011
no edit summary
This appendix provides the reference to the command line capabilities available when launching GRAMPS Gramps from the terminal.
{{grampsmanualcopyright}}
{{languages|Gramps_3.3_Wiki_Manual_-_Command_Line}}
 
== Available options ==
This section provides the reference list of all command line options available in GRAMPSGramps. If you want to know more than just a list of options, see next sections: [[Gramps-command line#Operation|Operation]] and [[Gramps-command line#Examples| Examples]]. A list is also available on [[Plugins Command Line|this page]].
=== List options ===
-l, print a list of known family trees
-L, print a detailed list of known family trees
 
=== Version options ===
 
-v or --version prints version of Gramps and dependencies,
information about environment settings and python and system paths
=== Format options ===
These formats contain all your data that is present in a family tree.
* '''gramps''' - 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 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 Gramps 3.x database: This format is available for import to support the old file format of GRAMPSGramps. 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 GRAMPSGramps
*'''ged''' - GEDCOM format: This format is available for import, and export. When not specified, it can be guessed if the filename ends with .ged
These formats contain a specific subset of your data
* '''csv''' - Comma Seperated Separated Value: This format is available for import and export. Be carefull careful 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 VCalandar 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 Gramps handle this automatically, just supply the familytree or filename you want to open:
python gramps.py 'My Fam Tree'
The first opens a family tree, the second imports a gedcom into an empty family tree.
Additionally, you can pass GRAMPS Gramps the name of the family tree to be opened:
* use this option : <pre>-O famtree</pre> or <pre>--open=famtree </pre>
{{Man tip| Tip |If no option is given, just a name, GRAMPS 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.}}
{{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.}}
python gramps.py -i test.grdb -i data.gramps
{{man tip | Tip |More than one file can be imported in one command. If this is the case, GRAMPS 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 <pre>-i</pre> flag. The files are imported in the specified order, i.e. <pre> -i file1 -i file2 </pre> and <pre> -i file2 -i file1 </pre> might produce different GRAMPS IDs in the resulting database.
=== Export options ===
The files destined for export can be specified with the <pre>-e filename</pre> or <pre>--export=filename</pre> option. The format can be specified with the <pre>-f</pre> 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 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.
will import test.grdb into Family Tree 1, and then export to a file !
{{man tip| Exporting more files |More than one file can be exported in one command. If this is the case, GRAMPS 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 <pre>-e</pre> flag. The files are written one by one, in the specified order.
==== 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"
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 an 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, ...
When more than one output action is given, each has to be preceded by <pre>-a</pre> 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
<pre>[</pre>
and must always end with a right square bracket
<pre>]</pre>
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
<pre>\</pre>
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 report -p name=hourglass_graph,note='[line one,line two]'
which shows that inside such a list different lines are separated by commas, and that spaces are acceptable since the quotation marks are already there for the square brackets.
 
But if you want to have a comma inside your report you have to somehow tell Gramps that comma is not one which separates lines. You do that by enclosing the line with the comma in quotation marks (either single or double).
 
But if you are already using a set of quotation marks (to enclose your square brackets) you have to use the other type to enclose
the line with your comma. Here is an example:
gramps -O "Family Tree 1" -a report -p name=hourglass_graph,note="['line one, also line one','line two, also line two']"
 
It is possible to include any character in a list but the details are beyond the scope of this command-line introduction to Gramps.
 
You will need to know the precise methods available in your particular command shell interpreter to include a character which is "special" to your shell or "special" to Gramps (like the comma in the example above) but in general you will have to "escape" it twice, once to your shell and once again to Gramps, since you don't want your shell to think it is some instruction it should pay attention to and you don't want Gramps to think that either.
 
==== tool action option ====
You can run most tools from the command line using the 'tool' action.
To see which ones, say:
gramps -O "Family Tree 1" -a tool -p show=all
To see a tool's available options, for instance the "verify" tool:
gramps -O "Family Tree 1" -a tool -p name=verify,show=all
To run a tool, for instance the "verify" tool:
gramps -O "Family Tree 1" -a tool -p name=verify
=== Force unlock option ===
-u, you can extend the -O flag with -u to force a locked family to be unlocked. This allows you to recover from a crash that leaves the famlily family tree (database) locked , from the command line. An example (to unlock the "Family Tree 1" database): gramps -O "Family Tree 1" -a report -u > /dev/null
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 , except 3.2, use behavior.database-path as the configuration variable to change.)
1) See all config values
-s or -config=-show
2) See a value:
--config=behavior.database-path
or
-c behavior.database-path
3) Set a value:
--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:
 
--config=behavior.use-tips:False --config=behavior.autoload:True
or
-c behavior.use-tips:False -c behavior.autoload:True
 
When all configuration variable(s) are set Gramps will start with these new values.
== Operation ==
If the first argument on the command line does not start with a dash (i.e. no flag), GRAMPS 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 <pre>-O</pre> flag is given, then GRAMPS 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 GRAMPSGramps. If you need to get data from multiple sources, use the importing options by using <pre>-i</pre> flag.}}
With or without the <pre>-O</pre> flag, there could be multiple imports, exports, and actions specified further on the command line by using <pre>-i</pre> , <pre>-e</pre> , and <pre>-a</pre> flags.
{{man note| Note |But opening must always be first!}}
If no <pre>-O</pre> or <pre>-i</pre> option is given, GRAMPS 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 <pre>-e</pre> or <pre>-a</pre> options are given, GRAMPS 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 GRAMPSGramps) or to stderr (if these are not handled). Use usual shell redirections of stdout and stderr to save messages and errors in files.
== Examples ==
:<pre>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</pre>
*To record the database resulting from all imports, supply -e flag (use -f if the filename does not allow GRAMPS Gramps to guess the format):
:<pre>gramps -i file1.ged -i file2.gpkg -e ~/new-package -f gramps-pkg</pre>
:<pre>gramps -i file1.ged -i file2.dpkg -e ~/new-package -f gramps-pkg >outfile 2>errfile </pre>
*To import three databases and start interactive GRAMPS Gramps session with the result:
:<pre>gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps </pre>
*Finally, to start normal interactive session type:
:<pre>gramps </pre>
== Environment variables==
GRAMPS 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. For technically advanced users who run multiple versions of Gramps, setting a different $GRAMPSHOME is a way to avoid interference between the different versions in the Gramps user directory.* '''LANG''' - is used by GRAMPS Gramps to determine which language file should be loaded.
{{man index|Gramps 3.3 Wiki Manual - Keybindings|Gramps 3.3 Wiki Manual - About|3.3}}
{{man indexlanguages|Gramps 3Gramps_3.3 Wiki Manual 3_Wiki_Manual_- Keybindings|Gramps 3.3 Wiki Manual - About|3.3_Command_Line}}
[[Category:Documentation]]
 
{{languages|Gramps_3.3_Wiki_Manual_-_Command_Line}}
2,186
edits

Navigation menu