Skip to content

Commit 101715b

Browse files
jdavidjdavid
committed
docs: review, in progress
1 parent d6c1d49 commit 101715b

File tree

12 files changed

+256
-195
lines changed

12 files changed

+256
-195
lines changed

‎docs/general.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
**********************************************************************
2+
General
3+
**********************************************************************
4+
5+
.. contents:: Contents
6+
:local:
7+
8+
9+
Constants
10+
=========
11+
12+
.. py:data:: LIBGIT2_VER_MAJOR
13+
.. py:data:: LIBGIT2_VER_MINOR
14+
.. py:data:: LIBGIT2_VER_REVISION
15+
.. py:data:: LIBGIT2_VER_VERSION
16+
17+
18+
Errors
19+
======
20+
21+
.. autoexception:: pygit2.GitError
22+
:members:
23+
:show-inheritance:
24+
:undoc-members:

‎docs/index.rst‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,32 +22,27 @@ Pygit2 links:
2222
Start:
2323

2424
.. toctree::
25-
:maxdepth: 2
25+
:maxdepth: 1
2626

2727
install
2828

2929
Usage guide:
3030

3131
.. toctree::
32-
:maxdepth: 2
32+
:maxdepth: 1
3333

34+
general
3435
repository
36+
oid
3537
objects
3638
references
3739
revparse
3840
log
3941
working-copy
4042
diff
43+
merge
4144
config
4245
remotes
43-
errors
44-
45-
More:
46-
47-
.. toctree::
48-
:maxdepth: 1
49-
50-
utils
5146

5247

5348
Indices and tables

docs/errors.rst renamed to docs/merge.rst

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,5 @@
11
**********************************************************************
2-
Errors
2+
Merge
33
**********************************************************************
44

5-
.. autoexception:: pygit2.GitError
6-
:members:
7-
:show-inheritance:
8-
:undoc-members:
5+
.. automethod:: pygit2.Repository.merge_base

‎docs/objects.rst‎

Lines changed: 91 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -2,91 +2,46 @@
22
Git objects
33
**********************************************************************
44

5+
There are four types of Git objects: blobs, trees, commits and tags. For each
6+
one pygit2 has a type, and all four types inherit from the base ``Object``
7+
type.
8+
9+
510
.. contents:: Contents
611
:local:
712

8-
In the first place Git is a key-value storage system. The keys are called
9-
OIDs, for Object id, and the values stored are called Objects.
1013

11-
Oids
14+
Objects
1215
=================
1316

14-
The oid is the `SHA-1 <http://en.wikipedia.org/wiki/SHA-1>`_ hash of an
15-
object. It is 20 bytes long:
16-
17-
- When we represent an oid as a 20 bytes Python string, we say it is a raw
18-
oid.
19-
20-
- When we represent an oid as a 40 chars Python string, we sayt it is a hex
21-
oid.
17+
The Object type is a base type, it is not possible to make instances of it, in
18+
any way.
2219

23-
However, most of the time we will use the Oid type. We can explicetly create
24-
an Oid object from its raw or hexadecimal form::
20+
It is the base type of the ``Blob``, ``Tree``, ``Commit`` and ``Tag`` types, so
21+
it is possible to check whether a Python value is an Object or not::
2522

26-
>>> hex = "cff3ceaefc955f0dbe1957017db181bc49913781"
27-
>>> oid1 = Oid(hex=hex)
28-
29-
>>> from binascii import unhexlify
30-
>>> raw = unhexlify(hex)
31-
>>> oid2 = Oid(raw=raw)
32-
33-
>>> print oid1 == oid2
23+
>>> from pygit2 import Object
24+
>>> commit = repository.revparse_single('HEAD')
25+
>>> print isinstance(commit, Object)
3426
True
3527

36-
And in the opposite direction, we can get the raw or hexadecimal form from
37-
an Oid object:
38-
39-
.. autoattribute:: pygit2.Oid.raw
40-
.. autoattribute:: pygit2.Oid.hex
41-
42-
The Oid type supports:
43-
44-
- rich comparisons, not just for equality, also: lesser-than, lesser-or-equal,
45-
etc.
46-
47-
- hashing, so Oid objects can be used as keys in a dictionary
48-
49-
50-
Python 2 and Python 3
51-
---------------------
52-
53-
There is a difference on how the library handles hex oids, depending on
54-
whether we are using Python 2 or 3.
55-
56-
- In Python 2, we can represent an hexadecimal oid using a bytes string
57-
(``str``) or a text string (``unicode``)
58-
59-
- In Python 3, hexadecimal oids can only be represented using unicode
60-
strings.
61-
28+
All Objects are immutable, they cannot be modified once they are created::
6229

63-
Objects
64-
=================
65-
66-
There are four types (commits, trees, blobs and tags), for each type pygit2
67-
has a Python class::
68-
69-
>>> # Show commits and trees
70-
>>> commit
71-
<pygit2.Commit object at 0x7f9d2f3000b0>
72-
>>> commit.tree
73-
<pygit2.Tree object at 0x7f9d2f3000f0>
74-
75-
These four classes (``Commit``, ``Tree``, ``Blob`` and ``Tag``) inherit from
76-
the ``Object`` base class, which provides shared behaviour. A Git object is
77-
identified by a unique *object id*, which is a binary byte string; this is
78-
often represented as an hexadecimal text string::
30+
>>> commit.message = u"foobar"
31+
Traceback (most recent call last):
32+
File "<stdin>", line 1, in <module>
33+
AttributeError: attribute 'message' of '_pygit2.Commit' objects is not writable
7934

80-
>>> commit.oid
81-
b'x\xde\xb5W\x8d\x01<\xdb\xdf\x08o\xa1\xd1\xa3\xe7\xd9\x82\xe8\x88\x8f'
82-
>>> commit.hex
83-
'78deb5578d013cdbdf086fa1d1a3e7d982e8888f'
35+
Derived types (blobs, trees, etc.) don't have a constructor, this means they
36+
cannot be created with the common idiom::
8437

85-
The API of pygit2 accepts both the raw object id and its hexadecimal
86-
representation, the difference is done based on its type (a byte or a text
87-
string).
38+
>>> from pygit2 import Blob
39+
>>> blob = Blob("data")
40+
Traceback (most recent call last):
41+
File "<stdin>", line 1, in <module>
42+
TypeError: cannot create '_pygit2.Blob' instances
8843

89-
Objects can not be modified once they have been created.
44+
New objects are created using an specific API we will see later.
9045

9146
This is the common interface for all Git objects:
9247

@@ -96,55 +51,38 @@ This is the common interface for all Git objects:
9651
.. automethod:: pygit2.Object.read_raw
9752

9853

99-
Commits
100-
=================
10154

102-
A commit is a snapshot of the working dir with meta informations like author,
103-
committer and others.
10455

105-
.. autoattribute:: pygit2.Commit.author
106-
.. autoattribute:: pygit2.Commit.committer
107-
.. autoattribute:: pygit2.Commit.message
108-
.. autoattribute:: pygit2.Commit.message_encoding
109-
.. autoattribute:: pygit2.Commit.tree
110-
.. autoattribute:: pygit2.Commit.parents
111-
.. autoattribute:: pygit2.Commit.commit_time
112-
.. autoattribute:: pygit2.Commit.commit_time_offset
11356

11457

115-
Signatures
116-
-------------
117-
118-
The author and committer attributes of commit objects are ``Signature``
119-
objects::
12058

121-
>>> commit.author
122-
<pygit2.Signature object at 0x7f75e9b1f5f8>
59+
Blobs
60+
=================
12361

124-
.. autoattribute:: pygit2.Signature.name
125-
.. autoattribute:: pygit2.Signature.email
126-
.. autoattribute:: pygit2.Signature.time
127-
.. autoattribute:: pygit2.Signature.offset
62+
A blob is equivalent to a file in a file system.::
12863

64+
>>> # create a blob out of memory
65+
>>> oid = repo.create_blob('foo bar')
66+
>>> blob = repo[oid]
67+
>>> blob.data
68+
'foo bar'
69+
>>> oid
70+
'\x96\xc9\x06um{\x91\xc4S"a|\x92\x95\xe4\xa8\rR\xd1\xc5'
12971

130-
Creating commits
131-
----------------
72+
.. autoattribute:: pygit2.Blob.data
73+
.. autoattribute:: pygit2.Blob.size
13274

133-
.. automethod:: pygit2.Repository.create_commit
75+
To create new blobs use the Repository API:
13476

135-
Commits can be created by calling the ``create_commit`` method of the
136-
repository with the following parameters::
77+
.. automethod:: pygit2.Repository.create_blob
78+
.. automethod:: pygit2.Repository.create_blob_fromworkdir
79+
.. automethod:: pygit2.Repository.create_blob_fromdisk
13780

138-
>>> author = Signature('Alice Author', 'alice@authors.tld')
139-
>>> committer = Signature('Cecil Committer', 'cecil@committers.tld')
140-
>>> tree = repo.TreeBuilder().write()
141-
>>> repo.create_commit(
142-
... 'refs/heads/master', # the name of the reference to update
143-
... author, committer, 'one line commit message\n\ndetailed commit message',
144-
... tree, # binary string representing the tree object ID
145-
... [] # list of binary strings representing parents of the new commit
146-
... )
147-
'#\xe4<u\xfe\xd6\x17\xa0\xe6\xa2\x8b\xb6\xdc35$\xcf-\x8b~'
81+
It is also possible to get the oid for a blob without really adding it to
82+
the Git object database:
83+
84+
.. autofunction:: pygit2.hash
85+
.. autofunction:: pygit2.hashfile
14886

14987

15088
Trees
@@ -200,28 +138,56 @@ Creating trees
200138
.. automethod:: pygit2.TreeBuilder.write
201139

202140

203-
Blobs
141+
Commits
204142
=================
205143

206-
A blob is equivalent to a file in a file system.::
144+
A commit is a snapshot of the working dir with meta informations like author,
145+
committer and others.
207146

208-
>>> # create a blob out of memory
209-
>>> oid = repo.create_blob('foo bar')
210-
>>> blob = repo[oid]
211-
>>> blob.data
212-
'foo bar'
213-
>>> oid
214-
'\x96\xc9\x06um{\x91\xc4S"a|\x92\x95\xe4\xa8\rR\xd1\xc5'
147+
.. autoattribute:: pygit2.Commit.author
148+
.. autoattribute:: pygit2.Commit.committer
149+
.. autoattribute:: pygit2.Commit.message
150+
.. autoattribute:: pygit2.Commit.message_encoding
151+
.. autoattribute:: pygit2.Commit.tree
152+
.. autoattribute:: pygit2.Commit.parents
153+
.. autoattribute:: pygit2.Commit.commit_time
154+
.. autoattribute:: pygit2.Commit.commit_time_offset
215155

216-
.. autoattribute:: pygit2.Blob.data
217-
.. autoattribute:: pygit2.Blob.size
218156

219-
Creating blobs
220-
--------------------
157+
Signatures
158+
-------------
159+
160+
The author and committer attributes of commit objects are ``Signature``
161+
objects::
162+
163+
>>> commit.author
164+
<pygit2.Signature object at 0x7f75e9b1f5f8>
165+
166+
.. autoattribute:: pygit2.Signature.name
167+
.. autoattribute:: pygit2.Signature.email
168+
.. autoattribute:: pygit2.Signature.time
169+
.. autoattribute:: pygit2.Signature.offset
170+
171+
172+
Creating commits
173+
----------------
174+
175+
.. automethod:: pygit2.Repository.create_commit
176+
177+
Commits can be created by calling the ``create_commit`` method of the
178+
repository with the following parameters::
179+
180+
>>> author = Signature('Alice Author', 'alice@authors.tld')
181+
>>> committer = Signature('Cecil Committer', 'cecil@committers.tld')
182+
>>> tree = repo.TreeBuilder().write()
183+
>>> repo.create_commit(
184+
... 'refs/heads/master', # the name of the reference to update
185+
... author, committer, 'one line commit message\n\ndetailed commit message',
186+
... tree, # binary string representing the tree object ID
187+
... [] # list of binary strings representing parents of the new commit
188+
... )
189+
'#\xe4<u\xfe\xd6\x17\xa0\xe6\xa2\x8b\xb6\xdc35$\xcf-\x8b~'
221190

222-
.. automethod:: pygit2.Repository.create_blob
223-
.. automethod:: pygit2.Repository.create_blob_fromworkdir
224-
.. automethod:: pygit2.Repository.create_blob_fromdisk
225191

226192
Tags
227193
=================

0 commit comments

Comments
 (0)