2222
2323class Git (object ):
2424"""
25- The Git class manages communication with the Git binary
25+ The Git class manages communication with the Git binary.
26+
27+ It provides a convenient interface to calling the Git binary, such as in::
28+
29+ g = Git( git_dir )
30+ g.init() # calls 'git init' program
31+ rval = g.ls_files()# calls 'git ls-files' program
32+
33+ ``Debugging``
34+ Set the GIT_PYTHON_TRACE environment variable print each invocation
35+ of the command to stdout.
36+ Set its value to 'full' to see details about the returned values.
2637 """
2738def __init__ (self ,git_dir ):
39+ """
40+ Initialize this instance with:
41+
42+ ``git_dir``
43+ Git directory we should work in. If None, we always work in the current
44+ directory as returned by os.getcwd()
45+ """
2846super (Git ,self ).__init__ ()
2947self .git_dir = git_dir
3048
3149def __getattr__ (self ,name ):
50+ """
51+ A convenience method as it allows to call the command as if it was
52+ an object.
53+ Returns
54+ Callable object that will execute call _call_process with your arguments.
55+ """
3256if name [:1 ]== '_' :
3357raise AttributeError (name )
3458return lambda * args ,** kwargs :self ._call_process (name ,* args ,** kwargs )
3559
3660@property
3761def get_dir (self ):
62+ """
63+ Returns
64+ Git directory we are working on
65+ """
3866return self .git_dir
3967
4068def execute (self ,command ,
@@ -49,7 +77,9 @@ def execute(self, command,
4977 the returned information (stdout)
5078
5179 ``command``
52- The command argument list to execute
80+ The command argument list to execute.
81+ It should be a string, or a sequence of program arguments. The
82+ program to execute is the first item in the args sequence or string.
5383
5484 ``istream``
5585 Standard input filehandle passed to subprocess.Popen.
@@ -68,11 +98,15 @@ def execute(self, command,
6898 ``with_raw_output``
6999 Whether to avoid stripping off trailing whitespace.
70100
71- Returns
72- str(output) # extended_output = False (Default)
73- tuple(int(status), str(output)) # extended_output = True
101+ Returns::
102+
103+ str(output) # extended_output = False (Default)
104+ tuple(int(status), str(stdout), str(stderr)) # extended_output = True
105+
106+ NOTE
107+ If you add additional keyword arguments to the signature of this method,
108+ you must update the execute_kwargs tuple housed in this module.
74109 """
75-
76110if GIT_PYTHON_TRACE and not GIT_PYTHON_TRACE == 'full' :
77111print ' ' .join (command )
78112
@@ -146,7 +180,8 @@ def _call_process(self, method, *args, **kwargs):
146180 the result as a String
147181
148182 ``method``
149- is the command
183+ is the command. Contained "_" characters will be converted to dashes,
184+ such as in 'ls_files' to call 'ls-files'.
150185
151186 ``args``
152187 is the list of arguments
@@ -156,7 +191,7 @@ def _call_process(self, method, *args, **kwargs):
156191 This function accepts the same optional keyword arguments
157192 as execute().
158193
159- Examples
194+ Examples::
160195 git.rev_list('master', max_count=10, header=True)
161196
162197 Returns