Changes

Jump to: navigation, search

Gramps 4.0 Wiki Manual - Command Line

9,479 bytes added, 09:50, 22 January 2014
m
Environment variables: formated MacOSX note
{{languages|Gramps_4.0_Wiki_Manual_-_Command_Line}}
 
{{#vardefine:chapter|C}}
{{#vardefine:figure|0}}
This appendix provides the reference to the command line capabilities available when launching Gramps from the terminal.
== Available options Start Gramps through the Command Line == Normally Gramps is started through the graphical user interface (GUI) on [[Gramps_4.0_Wiki_Manual_-_Getting_started#Start_Gramps|your platform]]. It is also possible to start Gramps using a command line interface (CLI). CLI use can* produce reports that are not available via the GUI, * create reports, do conversions etc. without opening a window and* can provide [[Gramps_4.0_Wiki_Manual_-_Main_Window#Seeing_all_the_error_messages|extra information]] in the event of problems. This section of the user manual describes how to start Gramps through the CLI, and the features that are available.
The way you start Gramps through the CLI depends on the operating system you are using. For simplicity of description, the examples of use below are written from the point of view of running Gramps on Linux. The examples would need to be changed for other platforms. === Linux === Only the Linux platform is officially supported as Gramps developers use and test the source code on that platform, fixing any problems that arise due to upgrades. Assuming you have used the standard Package Manager (either through a CLI or a GUI) for your Linux distribution, you start Gramps through the CLI by typing gramps === 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? Starting Gramps from the command line (cmd.exe) depends on where you have chosen to install Gramps.* Right click on the ??terminal Gramps application, or the corresponding item in the Start menu.* Note down the starting directory.* Select the whole of the command and copy (ctrl-C) it.* From the Start menu, start cmd.exe.* Change directory to the starting directory you noted down.* Right click and select Paste.* Press {{man key press|Enter}}. For example, this might be: cd "\Program Files\GrampsAIO64\bin "C:\Program Files\GrampsAIO64\bin\pythonw.exe" -EO ..\share\gramps\gramps.py When the instructions below tell you to type something after the start command, you just type this after the last line, for example: cd "\Program Files\GrampsAIO64\bin "C:\Program Files\GrampsAIO64\bin\pythonw.exe" -EO ..\share\gramps\gramps.py -L There are other ways to install Gramps for MS Windows, but these are much more complicated and are not covered here. === 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.Once you have a terminal window open, at the prompt type /path/to/Gramps.app/Contents/MacOS/GrampsIf you installed Gramps in Applications along with most of your other apps, that would be /Applications/Gramps.app/Contents/MacOS/GrampsYou may use any of the command-line options along with this. For example, to get a detailed listing of all of the Family Tree databases in your default Family Tree folder, you would use /Applications/Gramps.app/Content/MacOS/Gramps -L There are other ways to install Gramps for Mac OS X, but these are much more complicated and are not covered here. == Python options == In the examples of different platforms above, and also in commands in various files you may see some options after the 'python' command, for example '-EO' in "C:\Program Files\GrampsAIO64\bin\pythonw.exe" -EO ..\share\gramps\gramps.py -L It is important to distinguish between the '''python options''' in this case: -EOand the '''Gramps options''', in this case -L The '''python options''' that you may come across are:* -E Ignore all PYTHON* environment variables, e.g. PYTHONPATH and PYTHONHOME, that might be set.* -O Turn on basic optimizations. This changes the filename extension for compiled (bytecode) files from .pyc to .pyo. See also PYTHONOPTIMIZE. The -O 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]].* If it is not turned on, [[Debugging_Gramps#Add_debug_statements|debug statements]] may be activated.* If it is not turned on, additional features are available in the [[Gramps_4.0_Wiki_Manual_-_Plugin_Manager|Plugin Manager]]. The '''Gramps options''' are described below. == Available Gramps options == 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: [[Gramps-command line#Operation|Operation]] and [[Gramps-command line#Examples| Examples]]. A list The summary below is also available printed by gramps -h. 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[Plugins Command Line|this page: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:  Example of usage of Gramps command line interface 1. 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 tool -p name=check. 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 (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 4. 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 5. To import three databases and start interactive Gramps session with the result: gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps 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 Use the name=timeline,show=all to find out about all available options for the timeline report. To find out details of a particular option, use show=option_name , e.g. name=timeline,show=off string. To learn about available report names, use name=show string. 9. To convert a family tree on the fly to a .gramps xml file: gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml 10. 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 11. Finally, to start normal interactive session type: gramps Note: These examples are for bash shell. Syntax may be different for other shells and for Windows.
=== List options ===
-l, print a list of known family trees
[[Image:CommandLineExampleOutput-l-40.png|200px400px|thumb|leftright|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Command Line Example Output for ''python gramps.py -l'']]
{{-}}
-L, print a detailed list of known family trees
[[Image:CommandLineExampleOutput_L-40.png|200px400px|thumb|leftright|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Command Line Example Output for ''python gramps.py -L'']] <br clear="all"/> Note that dates are shown in the default LOCALE format. You change that at the system level. For example, on POSIX-based systems you could:  LC_TIME=en_AU.UTF-8 gramps -L 
{{-}}
-v or --version prints version of Gramps and dependencies,
information about environment settings and python and system paths
 
[[Image:CommandLineExampleOutput-v-40.png|200px|thumb|right|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Command Line Example Output for ''python gramps.py -v'']]
{{-}}
=== Format options ===
-s or --show
 
[[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:
{{man tip|1=Listing report options |2=Use the <tt>''name=timeline,show=all''</tt> to find out about all available options for the timeline report. To find out details of a particular option, use <tt>''show=option_name''</tt> , e.g. <tt>''name=timeline,show=off''</tt> string. To learn about available report names, use <tt>''name=show''</tt> string.}}
*To convert a grdb the bsddb database on the fly to a .gramps xml file:
:<pre>gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml</pre>
* '''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 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 Gramps.app/Contents/MacOS/Gramps. 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.}}
{{man index|Gramps 4.0 Wiki Manual - Keybindings|Gramps 4.0 Wiki Manual - User Directory|4.0}}
8,853
edits

Navigation menu