diff options
| -rw-r--r-- | doc/source/changes.rst | 2 | ||||
| -rw-r--r-- | doc/source/reference.rst | 3 | ||||
| -rw-r--r-- | doc/source/tutorial.rst | 72 | ||||
| -rw-r--r-- | git/cmd.py | 2 | ||||
| -rw-r--r-- | git/objects/base.py | 7 | ||||
| -rw-r--r-- | git/test/test_docs.py | 49 | ||||
| -rw-r--r-- | git/test/test_submodule.py | 2 |
7 files changed, 96 insertions, 41 deletions
diff --git a/doc/source/changes.rst b/doc/source/changes.rst index 60fe9725..4f67c1bb 100644 --- a/doc/source/changes.rst +++ b/doc/source/changes.rst @@ -7,6 +7,8 @@ Changelog * Added `Repo.merge_base()` implementation. See the `respective issue on github <https://github.com/gitpython-developers/GitPython/issues/169>`_ * `[include]` sections in git configuration files are now respected * Added `GitConfigParser.rename_section()` +* DOCS: special members like `__init__` are now listed in the API documentation +* DOCS: tutorial section was revised entirely * Added `Submodule.rename()` * **POSSIBLY BREAKING CHANGE**: As `rev_parse` will now throw `BadName` as well as `BadObject`, client code will have to catch both exception types. * A list of all issues can be found here: https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v0.3.6+-+Features%22+ diff --git a/doc/source/reference.rst b/doc/source/reference.rst index 7adc5328..8e0e296b 100644 --- a/doc/source/reference.rst +++ b/doc/source/reference.rst @@ -8,7 +8,8 @@ Objects.Base .. automodule:: git.objects.base :members: - :undoc-members: + :undoc-members: + :special-members: Objects.Blob ------------ diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst index 4921d07b..adce5910 100644 --- a/doc/source/tutorial.rst +++ b/doc/source/tutorial.rst @@ -8,42 +8,54 @@ GitPython Tutorial ================== -GitPython provides object model access to your git repository. This tutorial is composed of multiple sections, each of which explains a real-life usecase. +GitPython provides object model access to your git repository. This tutorial is composed of multiple sections, each of which explains a real-life usecase. -Initialize a Repo object -************************ +Meet the Repo type +****************** -The first step is to create a ``Repo`` object to represent your repository:: +The first step is to create a :class:`git.Repo <git.repo.base.Repo>` object to represent your repository. - from git import * - repo = Repo("/Users/mtrier/Development/git-python") - assert repo.bare == False +.. literalinclude:: ../../git/test/test_docs.py + :language: python + :start-after: def test_init_repo_object + :end-before: # ![1-test_init_repo_object] -In the above example, the directory ``/Users/mtrier/Development/git-python`` is my working repository and contains the ``.git`` directory. You can also initialize GitPython with a *bare* repository:: +In the above example, the directory ``self.rorepo.working_tree_dir`` equals ``/Users/mtrier/Development/git-python`` and is my working repository which contains the ``.git`` directory. You can also initialize GitPython with a *bare* repository. - repo = Repo.init("/var/git/git-python.git", bare=True) - assert repo.bare == True +.. literalinclude:: ../../git/test/test_docs.py + :language: python + :start-after: # [2-test_init_repo_object] + :end-before: # ![2-test_init_repo_object] -A repo object provides high-level access to your data, it allows you to create and delete heads, tags and remotes and access the configuration of the repository:: +A repo object provides high-level access to your data, it allows you to create and delete heads, tags and remotes and access the configuration of the repository. - repo.config_reader() # get a config reader for read-only access - repo.config_writer() # get a config writer to change configuration +.. literalinclude:: ../../git/test/test_docs.py + :language: python + :start-after: # [3-test_init_repo_object] + :end-before: # ![3-test_init_repo_object] -Query the active branch, query untracked files or whether the repository data has been modified:: +Query the active branch, query untracked files or whether the repository data has been modified. - repo.is_dirty() - False - repo.untracked_files - ['my_untracked_file'] +.. literalinclude:: ../../git/test/test_docs.py + :language: python + :start-after: # [4-test_init_repo_object] + :end-before: # ![4-test_init_repo_object] -Clone from existing repositories or initialize new empty ones:: +Clone from existing repositories or initialize new empty ones. - cloned_repo = repo.clone("to/this/path") - new_repo = Repo.init("path/for/new/repo") +.. literalinclude:: ../../git/test/test_docs.py + :language: python + :start-after: # [5-test_init_repo_object] + :end-before: # ![5-test_init_repo_object] -Archive the repository contents to a tar file:: +Archive the repository contents to a tar file. + +.. literalinclude:: ../../git/test/test_docs.py + :language: python + :start-after: # [6-test_init_repo_object] + :end-before: # ![6-test_init_repo_object] - repo.archive(open("repo.tar",'w')) +.. todo repo paths, heads, remotes, submodules Object Databases @@ -418,16 +430,12 @@ The previous approach would brutally overwrite the user's changes in the working Initializing a repository ************************* -In this example, we will initialize an empty repository, add an empty file to the index, and commit the change:: - - repo_dir = 'my-new-repo' - file_name = os.path.join(repo_dir, 'new-file') +In this example, we will initialize an empty repository, add an empty file to the index, and commit the change. - r = git.Repo.init(repo_dir) - # This function just creates an empty file ... - touch(file_name) - r.index.add([file_name]) - r.index.commit("initial commit") +.. literalinclude:: ../../git/test/test_docs.py + :language: python + :start-after: def test_add_file_and_commit + :end-before: # ![test_add_file_and_commit] Please have a look at the individual methods as they usually support a vast amount of arguments to customize their behavior. @@ -295,7 +295,7 @@ class Git(LazyMixin): :raise GitCommandError: if the return status is not 0""" status = self.proc.wait() if status != 0: - raise GitCommandError(self.args, status, self.proc.stderr.read().decode(defenc)) + raise GitCommandError(self.args, status, self.proc.stderr.read()) # END status handling return status # END auto interrupt diff --git a/git/objects/base.py b/git/objects/base.py index eb59b0a9..42876fc8 100644 --- a/git/objects/base.py +++ b/git/objects/base.py @@ -132,9 +132,11 @@ class IndexObject(Object): def __init__(self, repo, binsha, mode=None, path=None): """Initialize a newly instanced IndexObject + :param repo: is the Repo we are located in :param binsha: 20 byte sha1 - :param mode: is the stat compatible file mode as int, use the stat module + :param mode: + is the stat compatible file mode as int, use the stat module to evaluate the infomration :param path: is the path to the file in the file system, relative to the git repository root, i.e. @@ -149,7 +151,8 @@ class IndexObject(Object): self.path = path def __hash__(self): - """:return: + """ + :return: Hash of our path as index items are uniquely identifyable by path, not by their data !""" return hash(self.path) diff --git a/git/test/test_docs.py b/git/test/test_docs.py index 5ebae513..6befb9ea 100644 --- a/git/test/test_docs.py +++ b/git/test/test_docs.py @@ -6,21 +6,62 @@ # the BSD License: http://www.opensource.org/licenses/bsd-license.php import os -import git from git.test.lib import TestBase from gitdb.test.lib import with_rw_directory -from git.repo.fun import touch -class TestGit(TestBase): +class Tutorials(TestBase): + + @with_rw_directory + def test_init_repo_object(self, rw_dir): + from git import Repo + join = os.path.join + + # rorepo is a a Repo instance pointing to the git-python repository. + # For all you know, the first argument to Repo is a path to the repository + # you want to work with + repo = Repo(self.rorepo.working_tree_dir) + assert repo.bare == False + # ![1-test_init_repo_object] + + # [2-test_init_repo_object] + bare_empty_repo = Repo.init(join(rw_dir, 'bare-repo'), bare=True) + assert bare_empty_repo.bare == True + # ![2-test_init_repo_object] + + # [3-test_init_repo_object] + repo.config_reader() # get a config reader for read-only access + cw = repo.config_writer() # get a config writer to change configuration + cw.release() # call release() to be sure changes are written and locks are released + # ![3-test_init_repo_object] + + # [4-test_init_repo_object] + repo.is_dirty() + # False + repo.untracked_files + # ['my_untracked_file'] + # ![4-test_init_repo_object] + + # [5-test_init_repo_object] + assert repo.clone(join(rw_dir, 'to/this/path')).__class__ is Repo + assert Repo.init(join(rw_dir, 'path/for/new/repo')).__class__ is Repo + # ![5-test_init_repo_object] + + # [6-test_init_repo_object] + repo.archive(open(join(rw_dir, 'repo.tar'), 'w')) + # ![6-test_init_repo_object] @with_rw_directory def test_add_file_and_commit(self, rw_dir): + import git + repo_dir = os.path.join(rw_dir, 'my-new-repo') file_name = os.path.join(repo_dir, 'new-file') r = git.Repo.init(repo_dir) # This function just creates an empty file ... - touch(file_name) + open(file_name, 'wb').close() r.index.add([file_name]) r.index.commit("initial commit") + + # ![test_add_file_and_commit] diff --git a/git/test/test_submodule.py b/git/test/test_submodule.py index 49ab2586..1d4cf178 100644 --- a/git/test/test_submodule.py +++ b/git/test/test_submodule.py @@ -783,7 +783,7 @@ class TestSubmodule(TestBase): # Setup initial sandbox: # parent repo has one submodule, which has all the latest changes source_url = self._submodule_url() - sm_source_repo = git.Repo.clone_from(source_url, os.path.join(rw_dir, 'sm-source')) + sm_source_repo = git.Repo.clone_from(source_url, os.path.join(rw_dir, 'sm-source'), b='master') parent_repo = git.Repo.init(os.path.join(rw_dir, 'parent')) sm = parent_repo.create_submodule('mysubmodule', 'subdir/submodule', sm_source_repo.working_tree_dir, branch='master') |