gitpython-developers
diff --git a/‎doc/source/quickstart.rst‎
Lines changed: 81 additions & 4 deletions b/‎doc/source/quickstart.rst‎
Lines changed: 81 additions & 4 deletions
diff --git a/‎test/test_quick_doc.py‎
Lines changed: 68 additions & 3 deletions b/‎test/test_quick_doc.py‎
Lines changed: 68 additions & 3 deletions
@@ -49,14 +49,91 @@ git clone https://some_repo_url
 Usage
 ****************
 
-* git add filepath
+* $ 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
 
-* git commit -m message
-* git log file
-* git status
+        .. literalinclude:: ../../test/test_quick_doc.py
+            :language: python
+            :dedent: 8
+            :start-after: # [11-test_cloned_repo_object]
+            :end-before: # ![11-test_cloned_repo_object]
 
 
 
@@ -51,13 +51,78 @@ def test_cloned_repo_object(self, rw_dir):
         # [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 /dir1/file2.txt
+        update_file = 'dir1/file2.txt' # we'll use ./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 = [f"{local_dir}/{update_file}"]
+        add_file = [f"{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]
+        # ![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]
+        file = 'dir1/file2.txt' # relative path from git root
+        repo.iter_commits('--all', max_count=100, paths=file)
+
+        # 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', max_count=100, paths=file)
+        commits_for_file = [c for c in commits_for_file_generator]
+        commits_for_file
+
+        # Outputs: [<git.Commit "5076b368c97b01d83406ca095a301303da7f6fd4">,
+        # <git.Commit "d8dcd544e6fc5c00f6984424fc0cb4568abe518e">]
+        # ![6-test_cloned_repo_object]
+
+        # Untracked files - create new file
+        # [7-test_cloned_repo_object]
+        # We'll create a file5.txt
+
+        file5 = f'{local_dir}/file5.txt'
+        with open(file5, '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
+        file3 = f'{local_dir}/Downloads/file3.txt'
+        with open(file3, '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)
+        # 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]
+
+
+
+
+
+