README.txt

   1 python-git: Copyright (c) 2008 David Aguilar
   2
   3 The git module is a wrapper around the git command line interface.
   4 Any git command can be called by simply calling a function of
   5 the same name as the git command.
   6
   7 The command's output is returned in a string.
   8
   9 Passing the optional with_status=True keyword
  10 causes the function to returns a tuple of (status, output) instead.
  11
  12 To specify a dashed option, such as "--index", pass the name
  13 of the option as a keyword parameter set to true.
  14
  15 To specify options with dashes in their name, use
  16 underscores.  For example, --patch-with-raw becomes patch_with_raw.
  17 This applies to the command names as well.
  18
  19         import git
  20
  21         print git.rev_parse('HEAD')
  22         print git.diff('--', 'foo', cached=True)
  23         print git.commit('foo', F='COMMIT_MSG', s=True)
  24         print git.log('HEAD^..HEAD', patch_with_raw=True, abbrev=4)
  25
  26 Results in the following commands being executed:
  27
  28         [ 'git', 'rev-parse', 'HEAD' ]
  29         [ 'git', 'diff', '--cached', '--', 'foo' ]
  30         [ 'git', 'commit', '-FCOMMIT_MSG', '-s', 'foo' ]
  31         [ 'git', 'log', '--abbrev=4', '--patch-with-raw', 'HEAD^..HEAD' ]
  32
  33 Example:
  34
  35 >>> git.foo(with_status=True)
  36 (1, "git: 'foo' is not a git-command. See 'git --help'.")
  37
  38
  39 The strings returned by this module strip off trailing whitespace by
  40 default since it simplifies command usage.  To avoid that pass
  41 raw=True into any git.<command> function.
  42
  43 All git functions specified in the split string list below are present
  44 in the git.commands dictionary at import time.  Any that are not
  45 specified are added dynamically as modules import or use them.
  46
  47 For example:
  48         import git
  49         print git.foo()
  50
  51 Is perfectly valid but will raise an exception since git will return
  52 exit status 1.  To not raise exceptions, users can set
  53 git.RAISE_EXCEPTIONS=False or pass allow_errors=True to an
  54 individual command:
  55
  56         print git.foo(allow_errors=True)
  57
  58 would continue and print the standard git error message:
  59
  60 git: 'foo' is not a git-command. See 'git --help'.
  61
  62 Had git actually found a git-foo command, then its output would have
  63 been returned instead (as expected).
  64
  65 This is to allow seamless upgradeability with future as well as
  66 seamless integration with custom, user-defined git commands.
  67
  68 What this means is that the list of git commands included in this
  69 file is not strictly required for the proper execution of this module.
  70 We include the list, though, to provide convenience for users who
  71 use the python console's tab completion facilities.