gramps/data/man/en.rst

gramps(1)			     3.4.0			     gramps(1)



NAME
       gramps - Genealogical Research and Analysis Management Programming Sys‐
       tem.


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


DESCRIPTION
       Gramps is a Free/OpenSource genealogy program. It is written in Python,
       using  the GTK+/GNOME interface.  Gramps should seem familiar to anyone
       who has used other genealogy programs before such as Family Tree  Maker
       (TM),   Personal Ancestral Files (TM), or the GNU Geneweb.  It supports
       importing of the ever popular GEDCOM format which is used world wide by
       almost all other genealogy software.


OPTIONS
       gramps FILE
	      When  FILE is given (without any flags) as a family tree name or
	      as a family tree database directory, then it is  opened  and  an
	      interactive  session is started. If FILE is a file format under‐
	      stood by Gramps, an empty family tree is created	whose name  is
	      based  on  the  FILE  name and the data is imported into it. The
	      rest of the options is ignored. This way of launching  is  suit‐
	      able for using gramps as a handler for genealogical data in e.g.
	      web browsers. This invocation can accept any data format	native
	      to gramps, see below.


       -f,--format= FORMAT
	      Explicitly  specify  format of FILE given by preceding -i, or -e
	      option. If the -f option is not given for any FILE,  the	format
	      of that file is guessed according to its extension or MIME-type.

	      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  grdb,  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,  and  iso	(never
	      guessed, always specify with -f option).


       -l     Print a list of known family trees.


       -u,--force-unlock
	      Unlock a locked database.


       -O,--open= DATABASE
	      Open  DATABASE  which  must be an existing database directory or
	      existing family tree name.   If  no  action,  import  or	export
	      options  are  given on the command line then an interactive ses‐
	      sion is started using that database.


       -i,--import= FILE
	      Import data from FILE. If you haven't specified a database  then
	      a  temporary  database  is  used;  this is deleted when you exit
	      gramps.

	      When more than one input file is given, each has to be  preceded
	      by  -i flag. The files are imported in the specified order, i.e.
	      -i FILE1 -i FILE2 and -i FILE2 -i FILE1 might produce  different
	      gramps IDs in the resulting database.


       -a,--action= ACTION
	      Perform  ACTION  on  the	imported  data. This is done 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 OPTIONSTRING supplied by the -p flag).

	      The OPTIONSTRING should satisfy the following conditions:
	      It must not contain any  spaces.	 If  some  arguments  need  to
	      include  spaces,	the  string  should be enclosed with quotation
	      marks, i.e., follow the shell syntax.  Option string is  a  list
	      of  pairs  with name and value (separated by the equality 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 flag. The actions are performed one by one, in the specified order.


       -d,--debug= LOGGER_NAME
	      Enables  debug  logs  for  development  and testing. Look at the
	      source code for details

       --version
	      Prints the version number of gramps and then exits




Operation
       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.


       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, there could be multiple imports, exports,
       and actions specified further 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
       always is: 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  the  empty  database,  since
       there is no data to process, anyway.


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


       The error 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 std‐
       out and stderr to save messages and errors in files.


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  file‐
       names 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 -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 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 normal interactive session type:
	      gramps


ENVIRONMENT VARIABLES
       The program checks whether these environment variables are set:

       LANG  -	describe, which language to use: Ex.: for polish language this
       variable has to be set to pl_PL.UTF-8.

       GRAMPSHOME - if set, force Gramps to use  the  specified  directory  to
       keep program settings and databases there. By default, this variable is
       not set and gramps assumes that the folder with all databases and  pro‐
       file  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 writ‐
       ers, report generators, tools, and display filters to be added  without
       modification of the main program.

       In addition to generating direct printer output, report generators also
       target other systems, such as OpenOffice.org, AbiWord, HTML,  or  LaTeX
       to allow the users to modify the format to suit their needs.


KNOWN BUGS AND LIMITATIONS
FILES
       ${PREFIX}/bin/gramps
       ${PREFIX}/share/gramps
       ${HOME}/.gramps


AUTHORS
       Donald Allingham <don@gramps-project.org>
       http://gramps.sourceforge.net

       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 standard GNOME Help browser
       in the form of Gramps Manual. The manual is also available in XML  for‐
       mat  as gramps-manual.xml under doc/gramps-manual/$LANG in the official
       source distribution.

       The  developer  documentation  can  be  found  on  the  http://develop‐
       ers.gramps-project.org site.



January 2008			     3.4.0			     gramps(1)