# This module is part of GitPython and is released under the
# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
import gc
from test.lib import TestBase
from test.lib.helper import with_rw_directory
class QuickDoc(TestBase):
def tearDown(self):
gc.collect()
@with_rw_directory
def test_init_repo_object(self, path_to_dir):
# [1-test_init_repo_object]
# $ git init <path/to/dir>
from git import Repo
repo = Repo.init(path_to_dir)
# ![1-test_init_repo_object]
# [2-test_init_repo_object]
repo = Repo(path_to_dir)
# ![2-test_init_repo_object]
del repo # Avoids "assigned to but never used" warning. Doesn't go in the docs.
@with_rw_directory
def test_cloned_repo_object(self, local_dir):
from git import Repo
# Code to clone from url
# [1-test_cloned_repo_object]
# $ git clone <url> <local_dir>
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]
# $ git add <file>
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]
# $ git commit -m <message>
repo.index.commit("Update to file2")
# ![4-test_cloned_repo_object]
# [5-test_cloned_repo_object]
# $ git log <file>
# 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 = list(commits_for_file_generator)
commits_for_file
# Outputs: [<git.Commit "SHA1-HEX_HASH-2">,
# <git.Commit "SHA1-HEX-HASH-1">]
# ![6-test_cloned_repo_object]
# Untracked files - create new file
# [7-test_cloned_repo_object]
f = open(f"{local_dir}/untracked.txt", "w") # Creates an empty file.
f.close()
# ![7-test_cloned_repo_object]
# [8-test_cloned_repo_object]
repo.untracked_files
# Output: ['untracked.txt']
# ![8-test_cloned_repo_object]
# Modified files
# [9-test_cloned_repo_object]
# Let's 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.
# 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)
# Output
# Downloads/file3.txt
# ![11-test_cloned_repo_object]
# Compares staging area to head commit
# [11.1-test_cloned_repo_object]
diffs = repo.index.diff(repo.head.commit)
for d in diffs:
print(d.a_path)
# Output
# ![11.1-test_cloned_repo_object]
# [11.2-test_cloned_repo_object]
# Let's add untracked.txt.
repo.index.add(["untracked.txt"])
diffs = repo.index.diff(repo.head.commit)
for d in diffs:
print(d.a_path)
# Output
# untracked.txt
# ![11.2-test_cloned_repo_object]
# Compare commit to commit
# [11.3-test_cloned_repo_object]
first_commit = list(repo.iter_commits(all=True))[-1]
diffs = repo.head.commit.diff(first_commit)
for d in diffs:
print(d.a_path)
# Output
# dir1/file2.txt
# ![11.3-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 = list(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, entry.name, entry.type) for entry in tree]
files_and_dirs
# Output
# [(< git.Tree "SHA1-HEX_HASH" >, 'Downloads', 'tree'),
# (< git.Tree "SHA1-HEX_HASH" >, 'dir1', 'tree'),
# (< git.Blob "SHA1-HEX_HASH" >, 'file4.txt', 'blob')]
# ![14-test_cloned_repo_object]
# [15-test_cloned_repo_object]
def print_files_from_git(root, level=0):
for entry in root:
print(f'{"-" * 4 * level}| {entry.path}, {entry.type}')
if entry.type == "tree":
print_files_from_git(entry, level + 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] # The head commit tree.
# Output <git.Blob "SHA1-HEX-HASH">
# ![17-test_cloned_repo_object]
# Print latest file
# [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]
# Print previous tree
# [18.1-test_cloned_repo_object]
commits_for_file = list(repo.iter_commits(all=True, paths=print_file))
tree = commits_for_file[-1].tree # Gets the first commit tree.
blob = tree[print_file]
print(blob.data_stream.read().decode())
# Output
# File 2 version 1
# ![18.1-test_cloned_repo_object]