WIP Quick doc

doc/source/index.rst

@@ -9,6 +9,7 @@ GitPython Documentation
    :maxdepth: 2
 
    intro
+   quickstart
    tutorial
    reference
    roadmap

doc/source/quickstart.rst

@@ -0,0 +1,206 @@
+.. _quickdoc_toplevel:
+
+.. highlight:: python
+
+.. _quickdoc-label:
+
+==============================
+GitPython Quick Start Tutorial
+==============================
+Welcome to the GitPython Quickstart Guide! Designed for developers seeking a practical and interactive learning experience, this concise resource offers step-by-step code snippets to swiftly initialize/clone repositories, perform essential Git operations, and explore GitPython's capabilities. Get ready to dive in, experiment, and unleash the power of GitPython in your projects!
+
+All code presented here originated from `***** insert link **** <https://github.com/gitpython-developers/GitPython>`_ to assure correctness. Knowing this should also allow you to more easily run the code for your own testing purposes. All you need is a developer installation of git-python.
+
+git.Repo
+********
+
+There are a few ways to create a :class:`git.Repo <git.repo.base.Repo>` object
+
+An existing local path
+######################
+
+$ git init path/to/dir
+
+.. literalinclude:: ../../test/test_quick_doc.py
+    :language: python
+    :dedent: 8
+    :start-after: # [1-test_init_repo_object]
+    :end-before: # ![1-test_init_repo_object]
+
+Existing local git Repo
+#######################
+
+.. literalinclude:: ../../test/test_quick_doc.py
+    :language: python
+    :dedent: 8
+    :start-after: # [2-test_init_repo_object]
+    :end-before: # ![2-test_init_repo_object]
+
+Clone from URL
+##############
+
+For the rest of this tutorial we will use a clone from https://github.com/gitpython-developers/QuickStartTutorialFiles.git
+
+$ git clone https://github.com/gitpython-developers/QuickStartTutorialFiles.git
+
+.. literalinclude:: ../../test/test_quick_doc.py
+    :language: python
+    :dedent: 8
+    :start-after: # [1-test_cloned_repo_object]
+    :end-before: # ![1-test_cloned_repo_object]
+
+Usage
+****************
+
+* $ git add filepath
+
+.. literalinclude:: ../../test/test_quick_doc.py
+    :language: python
+    :dedent: 8
+    :start-after: # [2-test_cloned_repo_object]
+    :end-before: # ![2-test_cloned_repo_object]
+
+Now lets add the updated file to git
+
+.. literalinclude:: ../../test/test_quick_doc.py
+    :language: python
+    :dedent: 8
+    :start-after: # [3-test_cloned_repo_object]
+    :end-before: # ![3-test_cloned_repo_object]
+
+Notice the add method requires a list as a parameter
+
+* $ git commit -m message
+
+.. literalinclude:: ../../test/test_quick_doc.py
+    :language: python
+    :dedent: 8
+    :start-after: # [4-test_cloned_repo_object]
+    :end-before: # ![4-test_cloned_repo_object]
+
+* $ git log file
+
+A list of commits associated with a file
+
+.. literalinclude:: ../../test/test_quick_doc.py
+    :language: python
+    :dedent: 8
+    :start-after: # [5-test_cloned_repo_object]
+    :end-before: # ![5-test_cloned_repo_object]
+
+Notice this returns a generator object
+
+.. literalinclude:: ../../test/test_quick_doc.py
+    :language: python
+    :dedent: 8
+    :start-after: # [6-test_cloned_repo_object]
+    :end-before: # ![6-test_cloned_repo_object]
+
+returns list of :class:`Commit <git.objects.commit.Commit>` objects
+
+* $ git status
+
+    * Untracked files
+
+    Lets create a new file
+
+    .. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [7-test_cloned_repo_object]
+        :end-before: # ![7-test_cloned_repo_object]
+
+    .. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [8-test_cloned_repo_object]
+        :end-before: # ![8-test_cloned_repo_object]
+
+    * Modified files
+
+    .. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [9-test_cloned_repo_object]
+        :end-before: # ![9-test_cloned_repo_object]
+
+    .. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [10-test_cloned_repo_object]
+        :end-before: # ![10-test_cloned_repo_object]
+
+    returns a list of :class:`Diff <git.diff.Diff>` objects
+
+    .. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [11-test_cloned_repo_object]
+        :end-before: # ![11-test_cloned_repo_object]
+
+
+Trees & Blobs
+**************
+
+Latest Commit Tree
+##################
+
+.. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [12-test_cloned_repo_object]
+        :end-before: # ![12-test_cloned_repo_object]
+
+Any Commit Tree
+###############
+
+.. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [13-test_cloned_repo_object]
+        :end-before: # ![13-test_cloned_repo_object]
+
+Display level 1 Contents
+########################
+
+.. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [14-test_cloned_repo_object]
+        :end-before: # ![14-test_cloned_repo_object]
+
+Recurse through the Tree
+########################
+
+.. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [15-test_cloned_repo_object]
+        :end-before: # ![15-test_cloned_repo_object]
+
+.. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [16-test_cloned_repo_object]
+        :end-before: # ![16-test_cloned_repo_object]
+
+
+
+
+Printing text files
+####################
+
+.. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [17-test_cloned_repo_object]
+        :end-before: # ![17-test_cloned_repo_object]
+
+.. literalinclude:: ../../test/test_quick_doc.py
+        :language: python
+        :dedent: 8
+        :start-after: # [18-test_cloned_repo_object]
+        :end-before: # ![18-test_cloned_repo_object]
+
+
+

test/test_quick_doc.py

@@ -0,0 +1,176 @@
+import pytest
+
+
+from test.lib import TestBase
+from test.lib.helper import with_rw_directory
+
+
+class QuickDoc(TestBase):
+    def tearDown(self):
+        import gc
+
+        gc.collect()
+
+    @with_rw_directory
+    def test_init_repo_object(self, path_to_dir):
+
+        # [1-test_init_repo_object]
+        from git import Repo
+
+        repo = Repo.init(path_to_dir)  # git init path/to/dir
+       # ![1-test_init_repo_object]
+
+        # [2-test_init_repo_object]
+        repo = Repo(path_to_dir)
+        # ![2-test_init_repo_object]
+
+    @with_rw_directory
+    def test_cloned_repo_object(self, local_dir):
+
+        from git import Repo
+        import git
+        # code to clone from url
+        # [1-test_cloned_repo_object]
+        repo_url = "https://github.com/gitpython-developers/QuickStartTutorialFiles.git"
+
+        repo = Repo.clone_from(repo_url, local_dir)
+        # ![1-test_cloned_repo_object]
+
+        # code to add files
+        # [2-test_cloned_repo_object]
+        # We must make a change to a file so that we can add the update to git
+
+        update_file = 'dir1/file2.txt' # we'll use local_dir/dir1/file2.txt
+        with open(f"{local_dir}/{update_file}", 'a') as f:
+            f.write('\nUpdate version 2')
+        # ![2-test_cloned_repo_object]
+
+        # [3-test_cloned_repo_object]
+        add_file = [update_file]  # relative path from git root
+        repo.index.add(add_file)  # notice the add function requires a list of paths
+        # ![3-test_cloned_repo_object]
+
+        # code to commit - not sure how to test this
+        # [4-test_cloned_repo_object]
+        repo.index.commit("Update to file2")
+        # ![4-test_cloned_repo_object]
+
+        # [5-test_cloned_repo_object]
+        # relative path from git root
+        repo.iter_commits(all=True, max_count=10, paths=update_file)  # gets the last 10 commits from all branches
+
+        # Outputs: <generator object Commit._iter_from_process_or_stream at 0x7fb66c186cf0>
+
+        # ![5-test_cloned_repo_object]
+
+        # [6-test_cloned_repo_object]
+        commits_for_file_generator = repo.iter_commits(all=True, max_count=10, paths=update_file)
+        commits_for_file = [c for c in commits_for_file_generator]
+        commits_for_file
+
+        # Outputs: [<git.Commit "SHA1-HEX-HASH-1">,
+        # <git.Commit "SHA1-HEX-HASH-1">]
+        # ![6-test_cloned_repo_object]
+
+        # Untracked files - create new file
+        # [7-test_cloned_repo_object]
+        # We'll create a file5.txt
+
+        with open(f'{local_dir}/file5.txt', 'w') as f:
+            f.write('file5 version 1')
+        # ![7-test_cloned_repo_object]
+
+        # [8-test_cloned_repo_object]
+        repo.untracked_files
+        # Output: ['file5.txt']
+        # ![8-test_cloned_repo_object]
+
+        # Modified files
+        # [9-test_cloned_repo_object]
+        # Lets modify one of our tracked files
+
+        with open(f'{local_dir}/Downloads/file3.txt', 'w') as f:
+            f.write('file3 version 2')  # overwrite file 3
+        # ![9-test_cloned_repo_object]
+
+        # [10-test_cloned_repo_object]
+        repo.index.diff(None)  # compares staging area to working directory
+        repo.index.diff(repo.head.commit)  # compares staging area to last commit
+        # Output: [<git.diff.Diff object at 0x7fb66c076e50>,
+        # <git.diff.Diff object at 0x7fb66c076ca0>]
+        # ![10-test_cloned_repo_object]
+
+        # [11-test_cloned_repo_object]
+        diffs = repo.index.diff(None)
+        for d in diffs:
+            print(d.a_path)
+
+        # Downloads/file3.txt
+        # file4.txt
+        # ![11-test_cloned_repo_object]
+
+        '''Trees and Blobs'''
+
+        # Latest commit tree
+        # [12-test_cloned_repo_object]
+        tree = repo.head.commit.tree
+        # ![12-test_cloned_repo_object]
+
+        # Previous commit tree
+        # [13-test_cloned_repo_object]
+        prev_commits = [c for c in repo.iter_commits(all=True, max_count=10)]  # last 10 commits from all branches
+        tree = prev_commits[0].tree
+        # ![13-test_cloned_repo_object]
+
+        # Iterating through tree
+        # [14-test_cloned_repo_object]
+        files_and_dirs = [entry for entry in tree]
+        files_and_dirs
+
+        # Output
+        # [<git.Commit "SHA1-HEX-HASH-1">,
+        # <git.Commit "SHA1-HEX-HASH-1">,
+        # <git.Commit "SHA1-HEX-HASH-1">]
+
+        # ![14-test_cloned_repo_object]
+
+        # [15-test_cloned_repo_object]
+        def print_files_from_git(root, delim='-', i=0):
+            for entry in root:
+                print(f'{delim if i != 0 else ""}| {entry.path}, {entry.type}')
+                if entry.type == "tree":
+                    print_files_from_git(entry, delim * 4, i + 1)
+
+        # ![15-test_cloned_repo_object]
+
+        # [16-test_cloned_repo_object]
+        print_files_from_git(tree)
+
+        # Output
+        # | Downloads, tree
+        # ---- | Downloads / file3.txt, blob
+        # | dir1, tree
+        # ---- | dir1 / file1.txt, blob
+        # ---- | dir1 / file2.txt, blob
+        # | file4.txt, blob
+        # # ![16-test_cloned_repo_object]
+
+        # Printing text files
+        # [17-test_cloned_repo_object]
+        print_file = 'dir1/file2.txt'
+        tree[print_file]
+
+        # Output <git.Blob "SHA1-HEX-HASH-1">
+        # ![17-test_cloned_repo_object]
+
+        # [18-test_cloned_repo_object]
+        blob = tree[print_file]
+        print(blob.data_stream.read().decode())
+
+        # Output
+        # file 2 version 1
+        # Update version 2
+
+        # ![18-test_cloned_repo_object]
+
+