@@ -54,7 +54,7 @@ the history of your project.
5454 >>>heads= repo.heads
5555 >>>master= heads.master# lists can be accessed by name for convenience
5656 >>>master.commit# the commit pointed to by head called master
57- >>>master.rename(" new_name" # renameindividual heads or
57+ >>>master.rename(" new_name" # rename heads
5858
5959Tags are (usually immutable) references to a commit and/or a tag object.
6060
@@ -63,18 +63,22 @@ Tags are (usually immutable) references to a commit and/or a tag object.
6363 >>>tagref.tag# tags may have tag objects carrying additional information
6464 >>>tagref.commit# but they always point to commits
6565 >>>repo.delete_tag(tagref)# delete or
66- >>>repo.create_tag(" my_tag" # create tags using the repo
66+ >>>repo.create_tag(" my_tag" # create tags using the repo for convenience
6767
6868A symbolic reference is a special case of a reference as it points to another
6969reference instead of a commit
7070
71+ >>>head= repo.head# the head points to the active branch/ref
72+ >>>master= head.reference# retrieve the reference the head points to
73+ >>>master.commit# from here you use it as any other reference
74+
7175Modifying References
7276********************
7377You can easily create and delete reference types or modify where they point to.
7478
75- >>>repo.delete_head(' master'
76- >>>master= repo.create_head(' master'
77- >>>master.commit= ' HEAD~10' # set another commit without changing index or working tree
79+ >>>repo.delete_head(' master' # delete an existing head
80+ >>>master= repo.create_head(' master' # create a new one
81+ >>>master.commit= ' HEAD~10' # set branch to another commit without changing index or working tree
7882
7983Create or delete tags the same way except you may not change them afterwards
8084
@@ -89,9 +93,10 @@ or the working copy )
8993
9094Understanding Objects
9195*********************
92- An Object is anything storable in gits object database. Objects contain information
93- about their type, their uncompressed size as well as their data. Each object is
94- uniquely identified by a SHA1 hash, being 40 hexadecimal characters in size.
96+ An Object is anything storable in git's object database. Objects contain information
97+ about their type, their uncompressed size as well as the actual data. Each object is
98+ uniquely identified by a SHA1 hash, being 40 hexadecimal characters in size or 20
99+ bytes in size.
95100
96101Git only knows 4 distinct object types being Blobs, Trees, Commits and Tags.
97102
@@ -116,7 +121,7 @@ Basic fields are
116121'...'
117122 >>>len (hct.data)== hct.size
118123
119- Index Objects are objects that can be put intogits index. These objects are trees
124+ Index Objects are objects that can be put intogit's index. These objects are trees
120125and blobs which additionally know about their path in the filesystem as well as their
121126mode.
122127
@@ -130,8 +135,8 @@ mode.
130135100644
131136
132137Access blob data (or any object data) directly or using streams.
133- >>>htc.data# binary tree data
134- >>>htc.blobs[0 ].data_stream# stream object to read data from
138+ >>>htc.data# binary tree data as string ( inefficient )
139+ >>>htc.blobs[0 ].data_stream# stream object to read data from
135140 >>>htc.blobs[0 ].stream_data(my_stream)# write data to given stream
136141
137142
@@ -157,7 +162,7 @@ If you need paging, you can specify a number of commits to skip.
157162
158163The above will return commits 21-30 from the commit list.
159164
160- >>>headcommit= repo.headcommit .commit
165+ >>>headcommit= repo.head .commit
161166
162167 >>>headcommit.sha
163168'207c0c4418115df0d30820ab1a9acd2ea4bf4431'
@@ -228,9 +233,9 @@ Once you have a tree, you can get the contents.
228233Its useful to know that a tree behaves like a list with the ability to
229234query entries by name.
230235
231- >>>tree[0 ]== tree[' dir'
236+ >>>tree[0 ]== tree[' dir' # access by index and by sub-path
232237<git.Tree "f7eb5df2e465ab621b1db3f5714850d6732cfed2">
233- >>>for entryin tree:do_something (entry)
238+ >>>for entryin tree:do_something_with (entry)
234239
235240 >>>blob= tree[0 ][0 ]
236241 >>>blob.name
@@ -260,18 +265,18 @@ You can also get a tree directly from the repository if you know its name.
260265<git.Tree "6825a94104164d9f0f5632607bebd2a32a3579e5">
261266
262267As trees only allow direct access to their direct entries, use the traverse
263- method to obtain an iterator toaccess entries recursively.
268+ method to obtain an iterator totraverse entries recursively.
264269
265270 >>>tree.traverse()
266271<generator object at 0x7f6598bd65a8>
267- >>>for entryin traverse():do_something (entry)
272+ >>>for entryin traverse():do_something_with (entry)
268273
269274
270275The Index Object
271276****************
272- The git index is the stage containing changes to be writtento the next commit
277+ The git index is the stage containing changes to be writtenwith the next commit
273278or where merges finally have to take place. You may freely access and manipulate
274- this information using theIndex Object.
279+ this information using theIndexFile Object.
275280
276281 >>>index= repo.index
277282
@@ -289,7 +294,7 @@ Create new indices from other trees or as result of a merge. Write that result t
289294a new index.
290295
291296 >>>tmp_index= Index.from_tree(repo,' HEAD~1' # load a tree into a temporary index
292- >>>merge_index= Index.from_tree(repo,' HEAD' ' some_branch' # merge two trees
297+ >>>merge_index= Index.from_tree(repo,' base ' , ' HEAD' ' some_branch' # merge two trees three-way
293298 >>>merge_index.write(" merged_index"
294299
295300Handling Remotes
@@ -314,7 +319,7 @@ as if they where attributes.
314319'git@server:dummy_repo.git'
315320
316321Change configuration for a specific remote only
317- >>>o.config_writer.set(" url " " other_url"
322+ >>>o.config_writer.set(" pushurl " " other_url"
318323
319324Obtaining Diff Information
320325**************************
@@ -323,7 +328,7 @@ Diffs can generally be obtained by Subclasses of ``Diffable`` as they provide
323328the ``diff `` method. This operation yields a DiffIndex allowing you to easily access
324329diff information about paths.
325330
326- Diffs can be made between Index and Trees, Index and the working tree, trees and
331+ Diffs can be made betweenthe Index and Trees, Index and the working tree, trees and
327332trees as well as trees and the working copy. If commits are involved, their tree
328333will be used implicitly.
329334
@@ -338,9 +343,9 @@ will be used implicitly.
338343 >>>index.diff(' HEAD' # diff index against current HEAD tree
339344
340345The item returned is a DiffIndex which is essentially a list of Diff objects. It
341- provides additional filtering tofind what you might be looking for
346+ provides additional filtering toease finding what you might be looking for.
342347
343- >>>for diff_addedin wdiff.iter_change_type(' A' do_something (diff_added)
348+ >>>for diff_addedin wdiff.iter_change_type(' A' do_something_with (diff_added)
344349
345350Switching Branches
346351******************
@@ -349,7 +354,7 @@ head and reset your index and working copy to match. A simple manual way to do i
349354is the following one.
350355
351356 >>>repo.head.reference= repo.heads.other_branch
352- >>>repo.head.reset(index = True ,working_tree = True
357+ >>>repo.head.reset(index = True ,working_tree = True )
353358
354359The previous approach would brutally overwrite the user's changes in the working copy
355360and index though and is less sophisticated than a git-checkout for instance which