Dulwich.io dulwich / 7da7187
Convert CONTRIBUTING and README to rst. Jelmer Vernooij 27 days ago
4 changed file(s) with 150 addition(s) and 149 deletion(s). Raw diff Collapse all Expand all
+0
-55
CONTRIBUTING.md less more
0 All functionality should be available in pure Python. Optional C
1 implementations may be written for performance reasons, but should never
2 replace the Python implementation. The C implementations should follow the
3 kernel/git coding style.
4
5 Where possible include updates to NEWS along with your improvements.
6
7 New functionality and bug fixes should be accompanied by matching unit tests.
8
9 Coding style
10 ------------
11 Where possible, please follow PEP8 with regard to coding style.
12
13 Furthermore, triple-quotes should always be """, single quotes are ' unless
14 using " would result in less escaping within the string.
15
16 Public methods, functions and classes should all have doc strings. Please use
17 epydoc style docstrings to document parameters and return values.
18 You can generate the documentation by running "make doc".
19
20 Running the tests
21 -----------------
22 To run the testsuite, you should be able to simply run "make check". This
23 will run the tests using unittest.
24
25 $ make check
26
27 Tox configuration is also present as well as a Travis configuration file.
28
29 String Types
30 ------------
31 Like Linux, Git treats filenames as arbitrary bytestrings. There is no prescribed
32 encoding for these strings, and although it is fairly common to use UTF-8, any
33 raw byte strings are supported.
34
35 For this reason, Dulwich internally treats git-based filenames as bytestrings.
36 It is up to the Dulwich API user to encode and decode them if necessary. In the
37 future, the porcelain may accept unicode strings and convert them to bytestrings
38 as necessary on the fly (using sys.getfilesystemencoding()).
39
40 * git-repository related filenames: bytes
41 * object sha1 digests (20 bytes long): bytes
42 * object sha1 hexdigests (40 bytes long): str (bytestrings on python2, strings
43 on python3)
44
45 Merge requests
46 --------------
47 Please either send pull requests to the maintainer (jelmer@jelmer.uk) or create
48 new pull requests on GitHub.
49
50 Licensing
51 ---------
52 All contributions should be made under the same license that Dulwich itself
53 comes under: both Apache License, version 2.0 or later and GNU General Public
54 License, version 2.0 or later.
0 All functionality should be available in pure Python. Optional C
1 implementations may be written for performance reasons, but should never
2 replace the Python implementation. The C implementations should follow the
3 kernel/git coding style.
4
5 Where possible include updates to NEWS along with your improvements.
6
7 New functionality and bug fixes should be accompanied by matching unit tests.
8
9 Coding style
10 ------------
11 Where possible, please follow PEP8 with regard to coding style.
12
13 Furthermore, triple-quotes should always be """, single quotes are ' unless
14 using " would result in less escaping within the string.
15
16 Public methods, functions and classes should all have doc strings. Please use
17 epydoc style docstrings to document parameters and return values.
18 You can generate the documentation by running "make doc".
19
20 Running the tests
21 -----------------
22 To run the testsuite, you should be able to simply run "make check". This
23 will run the tests using unittest.
24
25 ::
26 $ make check
27
28 Tox configuration is also present as well as a Travis configuration file.
29
30 String Types
31 ------------
32 Like Linux, Git treats filenames as arbitrary bytestrings. There is no prescribed
33 encoding for these strings, and although it is fairly common to use UTF-8, any
34 raw byte strings are supported.
35
36 For this reason, Dulwich internally treats git-based filenames as bytestrings.
37 It is up to the Dulwich API user to encode and decode them if necessary. In the
38 future, the porcelain may accept unicode strings and convert them to bytestrings
39 as necessary on the fly (using sys.getfilesystemencoding()).
40
41 * git-repository related filenames: bytes
42 * object sha1 digests (20 bytes long): bytes
43 * object sha1 hexdigests (40 bytes long): str (bytestrings on python2, strings
44 on python3)
45
46 Merge requests
47 --------------
48 Please either send pull requests to the maintainer (jelmer@jelmer.uk) or create
49 new pull requests on GitHub.
50
51 Licensing
52 ---------
53 All contributions should be made under the same license that Dulwich itself
54 comes under: both Apache License, version 2.0 or later and GNU General Public
55 License, version 2.0 or later.
+0
-94
README.md less more
0 [![Build Status](https://travis-ci.org/dulwich/dulwich.png?branch=master)](https://travis-ci.org/dulwich/dulwich)
1 [![Windows Build status](https://ci.appveyor.com/api/projects/status/mob7g4vnrfvvoweb?svg=true)](https://ci.appveyor.com/project/jelmer/dulwich/branch/master)
2
3 This is the Dulwich project.
4
5 It aims to provide an interface to git repos (both local and remote) that
6 doesn't call out to git directly but instead uses pure Python.
7
8 **Main website**: [www.dulwich.io](https://www.dulwich.io/)
9
10 **License**: Apache License, version 2 or GNU General Public License, version 2 or later.
11
12 The project is named after the part of London that Mr. and Mrs. Git live in
13 in the particular Monty Python sketch.
14
15 Installation
16 ------------
17
18 By default, Dulwich' setup.py will attempt to build and install the optional C
19 extensions. The reason for this is that they significantly improve the performance
20 since some low-level operations that are executed often are much slower in CPython.
21
22 If you don't want to install the C bindings, specify the --pure argument to setup.py::
23
24 $ python setup.py --pure install
25
26 or if you are installing from pip::
27
28 $ pip install dulwich --global-option="--pure"
29
30 Note that you can also specify --global-option in a
31 [requirements.txt](https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers)
32 file, e.g. like this::
33
34 dulwich --global-option=--pure
35
36 Getting started
37 ---------------
38
39 Dulwich comes with both a lower-level API and higher-level plumbing ("porcelain").
40
41 For example, to use the lower level API to access the commit message of the
42 last commit:
43
44 >>> from dulwich.repo import Repo
45 >>> r = Repo('.')
46 >>> r.head()
47 '57fbe010446356833a6ad1600059d80b1e731e15'
48 >>> c = r[r.head()]
49 >>> c
50 <Commit 015fc1267258458901a94d228e39f0a378370466>
51 >>> c.message
52 'Add note about encoding.\n'
53
54 And to print it using porcelain:
55
56 >>> from dulwich import porcelain
57 >>> porcelain.log('.', max_entries=1)
58 --------------------------------------------------
59 commit: 57fbe010446356833a6ad1600059d80b1e731e15
60 Author: Jelmer Vernooij <jelmer@jelmer.uk>
61 Date: Sat Apr 29 2017 23:57:34 +0000
62
63 Add note about encoding.
64
65 Further documentation
66 ---------------------
67
68 The dulwich documentation can be found in docs/ and
69 [on the web](https://www.dulwich.io/docs/).
70
71 The API reference can be generated using pydoctor, by running "make pydoctor",
72 or [on the web](https://www.dulwich.io/apidocs).
73
74 Help
75 ----
76
77 There is a *#dulwich* IRC channel on the [Freenode](https://www.freenode.net/), and
78 [dulwich-announce](https://groups.google.com/forum/#!forum/dulwich-announce)
79 and [dulwich-discuss](https://groups.google.com/forum/#!forum/dulwich-discuss)
80 mailing lists.
81
82 Contributing
83 ------------
84
85 For a full list of contributors, see the git logs or [AUTHORS](AUTHORS).
86
87 If you'd like to contribute to Dulwich, see the [CONTRIBUTING](CONTRIBUTING.md)
88 file and [list of open issues](https://github.com/dulwich/dulwich/issues).
89
90 Supported versions of Python
91 ----------------------------
92
93 At the moment, Dulwich supports (and is tested on) CPython 2.7, 3.4, 3.5, 3.6 and Pypy.
0 [![Build Status](https://travis-ci.org/dulwich/dulwich.png?branch=master)](https://travis-ci.org/dulwich/dulwich)
1 [![Windows Build status](https://ci.appveyor.com/api/projects/status/mob7g4vnrfvvoweb?svg=true)](https://ci.appveyor.com/project/jelmer/dulwich/branch/master)
2
3 This is the Dulwich project.
4
5 It aims to provide an interface to git repos (both local and remote) that
6 doesn't call out to git directly but instead uses pure Python.
7
8 **Main website**: <https://www.dulwich.io/>
9
10 **License**: Apache License, version 2 or GNU General Public License, version 2 or later.
11
12 The project is named after the part of London that Mr. and Mrs. Git live in
13 in the particular Monty Python sketch.
14
15 Installation
16 ------------
17
18 By default, Dulwich' setup.py will attempt to build and install the optional C
19 extensions. The reason for this is that they significantly improve the performance
20 since some low-level operations that are executed often are much slower in CPython.
21
22 If you don't want to install the C bindings, specify the --pure argument to setup.py::
23
24 $ python setup.py --pure install
25
26 or if you are installing from pip::
27
28 $ pip install dulwich --global-option="--pure"
29
30 Note that you can also specify --global-option in a
31 `requirements.txt <https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers>`_
32 file, e.g. like this::
33
34 dulwich --global-option=--pure
35
36 Getting started
37 ---------------
38
39 Dulwich comes with both a lower-level API and higher-level plumbing ("porcelain").
40
41 For example, to use the lower level API to access the commit message of the
42 last commit::
43
44 >>> from dulwich.repo import Repo
45 >>> r = Repo('.')
46 >>> r.head()
47 '57fbe010446356833a6ad1600059d80b1e731e15'
48 >>> c = r[r.head()]
49 >>> c
50 <Commit 015fc1267258458901a94d228e39f0a378370466>
51 >>> c.message
52 'Add note about encoding.\n'
53
54 And to print it using porcelain::
55
56 >>> from dulwich import porcelain
57 >>> porcelain.log('.', max_entries=1)
58 --------------------------------------------------
59 commit: 57fbe010446356833a6ad1600059d80b1e731e15
60 Author: Jelmer Vernooij <jelmer@jelmer.uk>
61 Date: Sat Apr 29 2017 23:57:34 +0000
62
63 Add note about encoding.
64
65 Further documentation
66 ---------------------
67
68 The dulwich documentation can be found in docs/ and
69 `on the web <https://www.dulwich.io/docs/>`_.
70
71 The API reference can be generated using pydoctor, by running "make pydoctor",
72 or `on the web <https://www.dulwich.io/apidocs>`_.
73
74 Help
75 ----
76
77 There is a *#dulwich* IRC channel on the `Freenode <https://www.freenode.net/>`_, and
78 `dulwich-announce <https://groups.google.com/forum/#!forum/dulwich-announce>`_
79 and `dulwich-discuss <https://groups.google.com/forum/#!forum/dulwich-discuss>`_
80 mailing lists.
81
82 Contributing
83 ------------
84
85 For a full list of contributors, see the git logs or `AUTHORS <AUTHORS>`_.
86
87 If you'd like to contribute to Dulwich, see the `CONTRIBUTING <CONTRIBUTING.rst>`_
88 file and `list of open issues <https://github.com/dulwich/dulwich/issues>`_.
89
90 Supported versions of Python
91 ----------------------------
92
93 At the moment, Dulwich supports (and is tested on) CPython 2.7, 3.4, 3.5, 3.6 and Pypy.