PyDriller

https://pydriller.readthedocs.io/en/latest/
Admin
PyDriller is a Python framework that helps developers extract information from Git repositories,...
Tokens:11,917
Snippets:165
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Project Requirements

Source: https://pydriller.readthedocs.io/en/latest/_sources/intro.rst.txt

Install the project's requirements from the specified files and unzip test repositories. This is typically done after setting up a virtual environment.

```bash
$ pip install -r requirements.txt
$ pip install -r test-requirements.txt
$ unzip test-repos.zip
```

--------------------------------

### Setup Virtual Environment

Source: https://pydriller.readthedocs.io/en/latest/intro.html

Create and activate a Python 3 virtual environment for the project.

```bash
$ virtualenv -p python3 venv
$ source venv/bin/activate
```

--------------------------------

### Install Requirements and Prepare Tests

Source: https://pydriller.readthedocs.io/en/latest/intro.html

Install project dependencies and extract test repositories.

```bash
$ pip install -r requirements.txt
$ pip install -r test-requirements.txt
$ unzip test-repos.zip
```

--------------------------------

### Install PyDriller using pip

Source: https://pydriller.readthedocs.io/en/latest/_sources/intro.rst.txt

Use this command to install the latest version of PyDriller from the Python Package Index. This command also installs necessary dependencies.

```none
# pip install pydriller
```

--------------------------------

### Set up Virtual Environment

Source: https://pydriller.readthedocs.io/en/latest/_sources/intro.rst.txt

It is suggested to use a virtual environment for managing project dependencies. This example shows how to create and activate a Python 3 virtual environment named 'venv'.

```bash
$ virtualenv -p python3 venv
$ source venv/bin/activate
```

--------------------------------

### Configuring Repository Paths

Source: https://pydriller.readthedocs.io/en/latest/repository.html

Examples show how to configure the 'path_to_repo' parameter for the Repository class, supporting single local, multiple local, mixed local/remote, and single remote repositories.

```python
# analyze only 1 local repository
url = "repos/pydriller/"

# analyze 2 local repositories
url = ["repos/pydriller/", "repos/anotherrepo/"]

# analyze both local and remote
url = ["repos/pydriller/", "https://github.com/apache/hadoop.git", "repos/anotherrepo"]

# analyze 1 remote repository
url = "https://github.com/apache/hadoop.git"

```

--------------------------------

### Iterating Through Commits and Accessing Properties

Source: https://pydriller.readthedocs.io/en/latest/_sources/commit.rst.txt

This example shows how to traverse commits in a Git repository using PyDriller's Repository object and print details about each commit, such as its hash, author name, committer name, and committer date. Ensure you have PyDriller installed and replace 'path/to/the/repo' with the actual path to your Git repository.

```python
for commit in Repository('path/to/the/repo').traverse_commits():
    print(
        'The commit {} has been modified by {}, ' 
        'committed by {} in date {}'.format(
            commit.hash,
            commit.author.name,
            commit.committer.name,
            commit.committer_date
        )
    )
```

--------------------------------

### Traverse All Commits in a Repository

Source: https://pydriller.readthedocs.io/en/latest/repository.html

This is a basic example demonstrating how to iterate through all commits in a local repository and print their hashes. It initializes the Repository class with the path to the repository.

```python
for commit in Repository("/Users/dspadini/myrepo").traverse_commits():
    print(commit.hash)

```

--------------------------------

### Run Tests with Pytest

Source: https://pydriller.readthedocs.io/en/latest/_sources/intro.rst.txt

Execute the project's tests using the pytest framework after installing requirements and setting up the environment.

```bash
$ pytest
```

--------------------------------

### Invalid Commit Range Configuration

Source: https://pydriller.readthedocs.io/en/latest/repository.html

This example highlights an invalid configuration where both 'from_tag' and 'from_commit' are used simultaneously, which is not permitted.

```python
# !!!!! ERROR !!!!! THIS IS NOT POSSIBLE
Repository('path/to/the/repo', from_tag=from_tag, from_commit=from_commit).traverse_commits()

```

--------------------------------

### Traverse All Commits in a Repository

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Iterates through all commits in a specified local repository. This is a basic example to get started with PyDriller.

```python
for commit in Repository("/Users/dspadini/myrepo").traverse_commits():
    print(commit.hash)
```

--------------------------------

### Iterating and Printing Commit Information

Source: https://pydriller.readthedocs.io/en/latest/commit.html

This snippet demonstrates how to iterate through commits in a repository and print key details such as the commit hash, author name, committer name, and committer date. Ensure you have PyDriller installed and replace 'path/to/the/repo' with the actual path to your Git repository.

```python
for commit in Repository('path/to/the/repo').traverse_commits():
    print(
        'The commit {} has been modified by {}, '
        'committed by {} in date {}'.format(
            commit.hash,
            commit.author.name,
            commit.committer.name,
            commit.committer_date
        )
    )

```

--------------------------------

### Get Git Repository Information

Source: https://pydriller.readthedocs.io/en/latest/_sources/git.rst.txt

Retrieve various details from a Git repository, including commit lists, specific commits, files at the current commit, total commit count, and commits associated with tags.

```python
gr = Git('test-repos/test1')
gr.get_list_commits()                  # get the list of all commits
gr.get_commit('cc5b002')               # get the specific commit
gr.files()                             # get the list of files present in the repo at the current commit
gr.total_commits()                     # get total number of commits
gr.get_commit_from_tag('v1.15')        # get the commit with tag v1.15
```

--------------------------------

### Analyze Commits Between Two Dates

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Selects commits that fall within a specified date range (inclusive of the start date, exclusive of the end date). Both start and end dates must be provided.

```python
from datetime import datetime
dt1 = datetime(2016, 10, 8, 17, 0, 0)
dt2 = datetime(2016, 10, 8, 17, 59, 0)
Repository('path/to/the/repo', since=dt1, to=dt2).traverse_commits()
```

--------------------------------

### Git(path: str, conf=None)

Source: https://pydriller.readthedocs.io/en/latest/reference.html

Initializes a new Git repository instance.

```APIDOC
## Git(path: str, conf=None)

### Description
Initializes the Git repository object for the specified path.

### Parameters
- **path** (str) - Required - Path to the repository.
```

--------------------------------

### Repository.__init__

Source: https://pydriller.readthedocs.io/en/latest/reference.html

Initializes a new Repository instance to analyze one or more Git repositories.

```APIDOC
## Repository(path_to_repo, ...)

### Description
Initializes the main PyDriller class to run a study on local or remote repositories. The only required parameter is path_to_repo, which accepts a single path or a list of paths.

### Parameters
- **path_to_repo** (str | List[str]) - Required - Absolute path(s) to the repository or URL(s) to remote repositories.
- **single** (str | None) - Optional - Analyze a single commit.
- **since** (datetime | None) - Optional - Start date for the analysis.
- **to** (datetime | None) - Optional - End date for the analysis.
- **from_commit** (str | None) - Optional - Starting commit hash.
- **to_commit** (str | None) - Optional - Ending commit hash.
- **num_workers** (int) - Optional - Number of workers for parallel processing.
- **only_authors** (List[str] | None) - Optional - Filter commits by specific authors.
- **only_commits** (List[str] | None) - Optional - Filter by specific commit hashes.
- **clone_repo_to** (str | None) - Optional - Path to clone remote repositories.
```

--------------------------------

### Configure Repository Path

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Demonstrates various ways to specify the path to local and remote repositories for analysis. PyDriller handles cloning and cleanup for remote repositories.

```python
# analyze only 1 local repository
url = "repos/pydriller/"

# analyze 2 local repositories
url = ["repos/pydriller/", "repos/anotherrepo/"]

# analyze both local and remote
url = ["repos/pydriller/", "https://github.com/apache/hadoop.git", "repos/anotherrepo"]

# analyze 1 remote repository
url = "https://github.com/apache/hadoop.git"
```

--------------------------------

### checkout(hash: str)

Source: https://pydriller.readthedocs.io/en/latest/reference.html

Checks out the repository at the specified commit hash.

```APIDOC
## checkout(hash: str)

### Description
Checkout the repo at the specified commit. Note: This changes the state of the repo and should not be used with multiple threads.

### Parameters
- **hash** (str) - Required - Commit hash to checkout.
```

--------------------------------

### Run Tests

Source: https://pydriller.readthedocs.io/en/latest/intro.html

Execute the test suite using pytest.

```bash
$ pytest
```

--------------------------------

### Analyze a Single Commit by Hash

Source: https://pydriller.readthedocs.io/en/latest/repository.html

Demonstrates how to use the 'single' parameter to analyze only a specific commit identified by its hash.

```python
Repository('path/to/the/repo', single='6411e3096dd2070438a17b225f44475136e54e3a').traverse_commits()

```

--------------------------------

### Analyze Commits Within a Date Range

Source: https://pydriller.readthedocs.io/en/latest/repository.html

Illustrates using both 'since' and 'to' parameters to analyze commits within a specific date and time range.

```python
# Between 2 dates
dt1 = datetime(2016, 10, 8, 17, 0, 0)
dt2 = datetime(2016, 10, 8, 17, 59, 0)
Repository('path/to/the/repo', since=dt1, to=dt2).traverse_commits()

```

--------------------------------

### Calculate File Complexity Metrics

Source: https://pydriller.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Iterate over commits and their modified files to print the filename, its complexity, and the number of methods it contains. This relies on the Lizard tool for complexity analysis. Ensure the repository path is valid.

```python
for commit in Repository('path/to/the/repo').traverse_commits():
    for file in commit.modified_files:
        print('{} has complexity of {}, and it contains {} methods'.format(
              file.filename, file.complexity, len(file.methods)))
```

--------------------------------

### Analyze Commits Since a Specific Date

Source: https://pydriller.readthedocs.io/en/latest/repository.html

Shows how to use the 'since' parameter to analyze commits made after a specified date and time.

```python
# Since 8/10/2016
Repository('path/to/the/repo', since=datetime(2016, 10, 8, 17, 0, 0)).traverse_commits()

```

--------------------------------

### Analyze Commits Between Two Tags

Source: https://pydriller.readthedocs.io/en/latest/repository.html

Demonstrates how to use 'from_tag' and 'to_tag' parameters to analyze commits that fall between two specified tags.

```python
# Between tags
from_tag = 'tag1'
to_tag = 'tag2'
Repository('path/to/the/repo', from_tag=from_tag, to_tag=to_tag).traverse_commits()

```

--------------------------------

### Analyze Multiple Local and Remote Repositories

Source: https://pydriller.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Analyze a list of local and remote repositories sequentially. PyDriller clones remote repositories to a temporary location and deletes them afterward. The output includes project path, commit hash, and author date.

```python
urls = ["repos/repo1", "repos/repo2", "https://github.com/ishepard/pydriller.git", "repos/repo3", "https://github.com/apache/hadoop.git"]
for commit in Repository(path_to_repo=urls).traverse_commits():
    print("Project {}, commit {}, date {}".format(
           commit.project_path, commit.hash, commit.author_date))
```

--------------------------------

### ProcessMetric.count()

Source: https://pydriller.readthedocs.io/en/latest/reference.html

Calculates process metrics for the repository.

```APIDOC
## ProcessMetric.count()

### Description
Computes process metrics based on the repository data.

### Method
Method call
```

--------------------------------

### Analyze Commits Up To a Specific Date

Source: https://pydriller.readthedocs.io/en/latest/repository.html

Shows how to use the 'to' parameter to analyze commits made up to a specified date and time, including timezone information.

```python
# Up to a date
dt1 = datetime(2016, 10, 8, 17, 0, 0, tzinfo=to_zone)
Repository('path/to/the/repo', to=dt1).traverse_commits()

```

--------------------------------

### Iterate Over Commits in a Repository

Source: https://pydriller.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Use the Repository class to iterate over commits in a local Git repository and print commit hash and author name. Ensure you have a local repository at the specified path.

```python
for commit in Repository('path/to/the/repo').traverse_commits():
    print('Hash {}, author {}'.format(commit.hash, commit.author.name))
```

--------------------------------

### Traverse Commits and Collect DMM Values

Source: https://pydriller.readthedocs.io/en/latest/_sources/deltamaintainability.rst.txt

Iterates through commits in a repository and prints commit message along with DMM values for unit size, complexity, and interfacing. Files in unsupported languages are ignored.

```python
from pydriller import Repository

rm = Repository("https://github.com/avandeursen/dmm-test-repo")
for commit in rm.traverse_commits():
    print("| {} | {} | {} | {} |".format(
        commit.msg,
        commit.dmm_unit_size,
        commit.dmm_unit_complexity,
        commit.dmm_unit_interfacing
        ))

```

--------------------------------

### Calculate Code Churn Metrics

Source: https://pydriller.readthedocs.io/en/latest/_sources/processmetrics.rst.txt

Calculates total, maximum, and average code churn for each file within a commit range. Also retrieves the exact lines added and removed per file. Use this to analyze code modification activity.

```python
from pydriller.metrics.process.code_churn import CodeChurn
metric = CodeChurn(path_to_repo='path/to/the/repo',
                   from_commit='from commit hash',
                   to_commit='to commit hash')
files_count = metric.count()
files_max = metric.max()
files_avg = metric.avg()
added_removed_lines = metric.get_added_and_removed_lines()

print('Total code churn for each file: {}'.format(files_count))
print('Maximum code churn for each file: {}'.format(files_max))
print('Average code churn for each file: {}'.format(files_avg))
print('Lines added and removed for each file: {}'.format(added_removed_lines))
```

--------------------------------

### Calculate Contributor Experience

Source: https://pydriller.readthedocs.io/en/latest/_sources/processmetrics.rst.txt

This snippet calculates the percentage of lines authored by the highest contributor to a file within a specified commit range. It helps understand the concentration of work on a file.

```python
from pydriller.metrics.process.contributors_experience import ContributorsExperience
metric = ContributorsExperience(path_to_repo='path/to/the/repo',
                          	    from_commit='from commit hash',
                                    to_commit='to commit hash')
files = metric.count()
print('Files: {}'.format(files))
```

--------------------------------

### Clone PyDriller Repository

Source: https://pydriller.readthedocs.io/en/latest/_sources/intro.rst.txt

Clone the PyDriller git repository from GitHub to access its source code. Navigate into the cloned directory afterwards.

```bash
$ git clone https://github.com/ishepard/pydriller
$ cd pydriller
```

--------------------------------

### Collect DMM Values from Git Repository

Source: https://pydriller.readthedocs.io/en/latest/deltamaintainability.html

Iterates through commits in a Git repository and prints the commit message along with DMM values for unit size, complexity, and interfacing. Files in unsupported languages are ignored.

```python
from pydriller import Repository

rm = Repository("https://github.com/avandeursen/dmm-test-repo")
for commit in rm.traverse_commits():
        print("| {} | {} | {} | {} |".format(
                commit.msg,
                commit.dmm_unit_size,
                commit.dmm_unit_complexity,
                commit.dmm_unit_interfacing
                ))

```

--------------------------------

### Analyze a Single Commit by Hash

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Configures the Repository to analyze only a specific commit identified by its hash. This is useful for inspecting a particular change.

```python
Repository('path/to/the/repo', single='6411e3096dd2070438a17b225f44475136e54e3a').traverse_commits()
```

--------------------------------

### Checkout a Specific Commit or Branch

Source: https://pydriller.readthedocs.io/en/latest/_sources/git.rst.txt

Use this snippet to checkout a specific commit or branch in a Git repository. Ensure the repository path is correct.

```python
gr = Git('test-repos/git-1/')
gr.checkout('a7053a4dcd627f5f4f213dc9aa002eb1caf926f8')
```

--------------------------------

### Calculate Added Lines Metrics

Source: https://pydriller.readthedocs.io/en/latest/processmetrics.html

Calculates the total, maximum, and average number of lines added per file within a specified commit range. Average values are rounded to the nearest integer.

```python
from pydriller.metrics.process.lines_count import LinesCount
metric = LinesCount(path_to_repo='path/to/the/repo',
                    from_commit='from commit hash',
                    to_commit='to commit hash')

added_count = metric.count_added()
added_max = metric.max_added()
added_avg = metric.avg_added()
print('Total lines added per file: {}'.format(added_count))
print('Maximum lines added per file: {}'.format(added_max))
print('Average lines added per file: {}'.format(added_avg))
```

--------------------------------

### Filter for Release Commits

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Includes only commits that are tagged as releases. Note that 'release' is a GitHub term and PyDriller identifies these based on commit tags.

```python
Repository('path/to/the/repo', only_releases=True).traverse_commits()
```

--------------------------------

### Calculate Change Set Metrics by Date Range

Source: https://pydriller.readthedocs.io/en/latest/_sources/processmetrics.rst.txt

Calculates the maximum and average number of files committed together between two specific dates. This is useful for analyzing file grouping trends over time.

```python
from datetime import datetime
from pydriller.metrics.process.change_set import ChangeSet
metric = ChangeSet(path_to_repo='path/to/the/repo',
                   since=datetime(2019, 1, 1),
                   to=datetime(2019, 12, 31))

maximum = metric.max()
average = metric.avg()
print('Maximum number of files committed together: {}'.format(maximum))
print('Average number of files committed together: {}'.format(average))
```

--------------------------------

### Print Modified Files Per Commit

Source: https://pydriller.readthedocs.io/en/latest/_sources/tutorial.rst.txt

Iterate through commits and their modified files to print the author's name, the filename, and the commit hash. This snippet requires a local repository path.

```python
for commit in Repository('path/to/the/repo').traverse_commits():
    for file in commit.modified_files:
        print('Author {} modified {} in commit {}'.format(commit.author.name, file.filename, commit.hash))
```

--------------------------------

### Calculate Change Set Metrics by Commit Hash

Source: https://pydriller.readthedocs.io/en/latest/_sources/processmetrics.rst.txt

Calculates the maximum and average number of files committed together within a specified commit range. Use this to understand how files are grouped in commits.

```python
from pydriller.metrics.process.change_set import ChangeSet
metric = ChangeSet(path_to_repo='path/to/the/repo',
                   from_commit='from commit hash',
                   to_commit='to commit hash')

maximum = metric.max()
average = metric.avg()
print('Maximum number of files committed together: {}'.format(maximum))
print('Average number of files committed together: {}'.format(average))
```

--------------------------------

### Calculate Added Lines Metrics

Source: https://pydriller.readthedocs.io/en/latest/_sources/processmetrics.rst.txt

This snippet calculates the total, maximum, and average number of lines added per file within a specified commit range. The average is rounded to the nearest integer.

```python
from pydriller.metrics.process.lines_count import LinesCount
metric = LinesCount(path_to_repo='path/to/the/repo',
                        from_commit='from commit hash',
                        to_commit='to commit hash')

added_count = metric.count_added()
added_max = metric.max_added()
added_avg = metric.avg_added()
print('Total lines added per file: {}'.format(added_count))
print('Maximum lines added per file: {}'.format(added_max))
print('Average lines added per file: {}'.format(added_avg))
```

--------------------------------

### Calculate Contributor Experience

Source: https://pydriller.readthedocs.io/en/latest/processmetrics.html

Measures the percentage of lines authored by the highest contributor to a file within a specified commit range.

```python
from pydriller.metrics.process.contributors_experience import ContributorsExperience
metric = ContributorsExperience(path_to_repo='path/to/the/repo',
                                from_commit='from commit hash',
                                to_commit='to commit hash')
files = metric.count()
print('Files: {}'.format(files))
```

--------------------------------

### Filter Commits by Branch

Source: https://pydriller.readthedocs.io/en/latest/repository.html

Demonstrates how to use the 'only_in_branch' parameter to restrict analysis to commits belonging to a specific branch.

```python
# Only commits in branch1
Repository('path/to/the/repo', only_in_branch='branch1').traverse_commits()

```

--------------------------------

### Iterate Through Modified Files in Commits

Source: https://pydriller.readthedocs.io/en/latest/modifiedfile.html

Iterate over commits in a repository and print details about each modified file, including author, filename, change type, and complexity. This snippet demonstrates basic access to ModifiedFile attributes.

```python
for commit in Repository('path/to/the/repo').traverse_commits():
    for m in commit.modified_files:
        print(
            "Author {}".format(commit.author.name),
            " modified {}".format(m.filename),
            " with a change type of {}".format(m.change_type.name),
            " and the complexity is {}".format(m.complexity)
        )

```

--------------------------------

### Analyze Commits Up To a Specific Date

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Retrieves commits made up to a certain date and time. The `to` parameter specifies the upper bound for the commit analysis.

```python
from datetime import datetime
# Assuming to_zone is defined elsewhere, e.g., from dateutil.tz import gettz
# to_zone = gettz('UTC')
dt1 = datetime(2016, 10, 8, 17, 0, 0, tzinfo=to_zone)
Repository('path/to/the/repo', to=dt1).traverse_commits()
```

--------------------------------

### Calculate Removed Lines Metrics

Source: https://pydriller.readthedocs.io/en/latest/processmetrics.html

Calculates the total, maximum, and average number of lines removed per file within a specified commit range. Average values are rounded to the nearest integer.

```python
from pydriller.metrics.process.lines_count import LinesCount
metric = LinesCount(path_to_repo='path/to/the/repo',
                    from_commit='from commit hash',
                    to_commit='to commit hash')

removed_count = metric.count_removed()
removed_max = metric.max_removed()
removed_avg = metric.avg_removed()
print('Total lines removed per file: {}'.format(removed_count))
print('Maximum lines removed per file: {}'.format(removed_max))
print('Average lines removed per file: {}'.format(removed_avg))
```

--------------------------------

### Repository.traverse_commits()

Source: https://pydriller.readthedocs.io/en/latest/reference.html

The primary method for iterating through commits in a repository.

```APIDOC
## Repository.traverse_commits()

### Description
Iterates through the commits of the repository. This is the main entry point for analyzing repository history.

### Method
Method call

### Parameters
- **None explicitly documented in source**
```

--------------------------------

### Iterating Through Modified Files in a Commit

Source: https://pydriller.readthedocs.io/en/latest/_sources/modifiedfile.rst.txt

This snippet shows how to iterate through all commits in a repository and then through each modified file within those commits. It prints the author's name, the modified filename, the change type, and the file's complexity. Ensure you have the Repository object initialized with the correct path to your Git repository.

```python
for commit in Repository('path/to/the/repo').traverse_commits():
    for m in commit.modified_files:
        print(
            "Author {}".format(commit.author.name),
            " modified {}".format(m.filename),
            " with a change type of {}".format(m.change_type.name),
            " and the complexity is {}".format(m.complexity)
        )
```

--------------------------------

### Analyze Commits Between Two Tags

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Filters commits to include only those between two specified tags. This allows analysis of changes introduced between specific release points.

```python
from_tag = 'tag1'
to_tag = 'tag2'
Repository('path/to/the/repo', from_tag=from_tag, to_tag=to_tag).traverse_commits()
```

--------------------------------

### Calculate Removed Lines Metrics

Source: https://pydriller.readthedocs.io/en/latest/_sources/processmetrics.rst.txt

This snippet calculates the total, maximum, and average number of lines removed per file within a specified commit range. The average is rounded to the nearest integer.

```python
from pydriller.metrics.process.lines_count import LinesCount
metric = LinesCount(path_to_repo='path/to/the/repo',
                        from_commit='from commit hash',
                        to_commit='to commit hash')

removed_count = metric.count_removed()
removed_max = metric.max_removed()
removed_avg = metric.avg_removed()
print('Total lines removed per file: {}'.format(removed_count))
print('Maximum lines removed per file: {}'.format(removed_max))
print('Average lines removed per file: {}'.format(removed_avg))
```

--------------------------------

### Calculate Median Hunks Count

Source: https://pydriller.readthedocs.io/en/latest/processmetrics.html

Calculates the median number of hunks (continuous blocks of changes) for each modified file within a specified commit range. This helps assess code fragmentation.

```python
from pydriller.metrics.process.hunks_count import HunksCount
metric = HunksCount(path_to_repo='path/to/the/repo',
                    from_commit='from commit hash',
                    to_commit='to commit hash')
files = metric.count()
print('Files: {}'.format(files))
```

--------------------------------

### Repository.traverse_commits()

Source: https://pydriller.readthedocs.io/en/latest/reference.html

Analyzes all specified commits in a repository and returns a generator of Commit objects.

```APIDOC
## Repository.traverse_commits()

### Description
Analyzes all the specified commits (all of them by default) in a repository, returning a generator of commits.

### Parameters
- **path_to_repo** (Union[str, List[str]]) - Required - Absolute path (or list of absolute paths) to the repository(ies) to analyze
- **single** (str) - Optional - Hash of a single commit to analyze
- **since** (datetime) - Optional - Starting date
- **since_as_filter** (datetime) - Optional - Starting date (scans all commits, does not stop at first commit with date < since_as_filter)
- **to** (datetime) - Optional - Ending date
- **from_commit** (str) - Optional - Starting commit (only if since is None)
- **to_commit** (str) - Optional - Ending commit (only if to is None)
- **from_tag** (str) - Optional - Starting the analysis from specified tag (only if since and from_commit are None)
- **to_tag** (str) - Optional - Ending the analysis from specified tag (only if to and to_commit are None)
- **include_refs** (bool) - Optional - Whether to include refs and HEAD in commit analysis
- **include_remotes** (bool) - Optional - Whether to include remote commits in analysis
- **num_workers** (int) - Optional - Number of workers (i.e., threads). Please note, if num_workers > 1 the commits order is not maintained.
- **only_in_branch** (str) - Optional - Only commits in this branch will be analyzed
- **only_modifications_with_file_types** (List[str]) - Optional - Only modifications with that file types will be analyzed
- **only_no_merge** (bool) - Optional - If True, merges will not be analyzed
- **only_authors** (List[str]) - Optional - Only commits of these authors will be analyzed (the check is done on the username, NOT the email)
- **only_commits** (List[str]) - Optional - Only these commits will be analyzed
- **only_releases** (bool) - Optional - Analyze only tagged commits
- **histogram_diff** (bool) - Optional - Add the “–histogram” option when asking for the diff
- **skip_whitespaces** (bool) - Optional - Add the “-w” option when asking for the diff
- **clone_repo_to** (str) - Optional - If the repo under analysis is remote, clone the repo to the specified directory
- **filepath** (str) - Optional - Only commits that modified this file will be analyzed
- **include_deleted_files** (bool) - Optional - Include commits modifying a deleted file (useful when analyzing a deleted filepath)
- **order** (str) - Optional - Order of commits. It can be one of: ‘date-order’, ‘author-date-order’, ‘topo-order’, or ‘reverse’. If order=None, PyDriller returns the commits from the oldest to the newest.
- **use_mailmap** (bool) - Optional - Map names and emails of authors and committers to canonical values when a .mailmap file is present in the repository.

### Response
- **Generator[Commit, None, None]** - A generator yielding Commit objects.
```

--------------------------------

### Calculate Median Hunks Count

Source: https://pydriller.readthedocs.io/en/latest/_sources/processmetrics.rst.txt

Use this to determine the median number of hunks (continuous blocks of changes) per file within a given commit range. This metric indicates how fragmented the changes are within files.

```python
from pydriller.metrics.process.hunks_count import HunksCount
metric = HunksCount(path_to_repo='path/to/the/repo',
                        from_commit='from commit hash',
                        to_commit='to commit hash')
files = metric.count()
print('Files: {}'.format(files))
```

--------------------------------

### Filter by Specific Commit Hashes

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Analyzes only a predefined list of commit hashes. This provides precise control over which commits are included in the analysis.

```python
Repository('path/to/the/repo', only_commits=['commit_hash_1', 'commit_hash_2']).traverse_commits()
```

--------------------------------

### get_commits_modified_file(filepath: str, include_deleted_files=False)

Source: https://pydriller.readthedocs.io/en/latest/reference.html

Returns a list of commit hashes that modified a specific file.

```APIDOC
## get_commits_modified_file(filepath: str, include_deleted_files=False)

### Description
Given a filepath, returns all the commits that modified this file (following renames).

### Parameters
- **filepath** (str) - Required - Path to the file.
- **include_deleted_files** (bool) - Optional - If True, include commits that modified a deleted file.

### Returns
- **List[str]** - List of commit hashes.
```

--------------------------------

### Count Commits Per File

Source: https://pydriller.readthedocs.io/en/latest/_sources/processmetrics.rst.txt

Counts the number of commits made to each modified file within a specified evolution period. Use this to understand file commit frequency.

```python
from pydriller.metrics.process.commits_count import CommitsCount
metric = CommitsCount(path_to_repo='path/to/the/repo',
                          from_commit='from commit hash',
                          to_commit='to commit hash')
files = metric.count()
print('Files: {}'.format(files))
```

--------------------------------

### Git.get_commit()

Source: https://pydriller.readthedocs.io/en/latest/reference.html

Retrieves a specific commit from the Git repository by its hash.

```APIDOC
## Git.get_commit()

### Description
Fetches a commit object from the repository using the provided commit hash.

### Method
Method call

### Parameters
- **hash** (string) - The commit hash to retrieve.
```

--------------------------------

### Analyze Commits Since a Specific Date

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Filters commits to include only those created after a specified date and time. Ensure the datetime object is correctly formatted.

```python
from datetime import datetime
Repository('path/to/the/repo', since=datetime(2016, 10, 8, 17, 0, 0)).traverse_commits()
```

--------------------------------

### get_list_commits(rev='HEAD', **kwargs)

Source: https://pydriller.readthedocs.io/en/latest/reference.html

Returns a generator of all commits in the repository.

```APIDOC
## get_list_commits(rev='HEAD', **kwargs)

### Description
Return a generator of all commits in the repository.

### Returns
- **Generator[Commit]** - Generator of all commits in the repo.
```

--------------------------------

### Count Commits Per File

Source: https://pydriller.readthedocs.io/en/latest/processmetrics.html

This snippet counts the number of commits made to each modified file within a specified evolution period defined by commit hashes. The results are printed as a dictionary where keys are file paths and values are commit counts.

```python
from pydriller.metrics.process.commits_count import CommitsCount
metric = CommitsCount(path_to_repo='path/to/the/repo',
                      from_commit='from commit hash',
                      to_commit='to commit hash')
files = metric.count()
print('Files: {}'.format(files))
```

--------------------------------

### Filter Commits by File Path

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Use `filepath` to analyze commits that modified a specific file. Accepts a single file path.

```python
Repository('path/to/the/repo', filepath='Matricula.javax').traverse_commits()
```

--------------------------------

### Filter Commits by Author

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Use `only_authors` to analyze commits made by specific authors. Accepts a list of author names.

```python
Repository('path/to/the/repo', only_authors=['ishepard']).traverse_commits()
```

--------------------------------

### Filter Commits by Branch and Exclude Merges

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Combine `only_in_branch` and `only_no_merge` to analyze commits in a specific branch, excluding merge commits.

```python
Repository('path/to/the/repo', only_in_branch='branch1', only_no_merge=True).traverse_commits()
```

--------------------------------

### Count Contributors for a File

Source: https://pydriller.readthedocs.io/en/latest/_sources/processmetrics.rst.txt

Use this snippet to count the total number of unique developers who contributed to a specific file within a given commit range. It also allows counting 'minor' contributors (less than 5% contribution).

```python
from pydriller.metrics.process.contributors_count import ContributorsCount
metric = ContributorsCount(path_to_repo='path/to/the/repo',
                           from_commit='from commit hash',
                           to_commit='to commit hash')
count = metric.count()
minor = metric.count_minor()
print('Number of contributors per file: {}'.format(count))
print('Number of "minor" contributors per file: {}'.format(minor))
```

--------------------------------

### PyDriller Citation Information

Source: https://pydriller.readthedocs.io/en/latest/_sources/intro.rst.txt

This is the BibTeX entry for citing PyDriller in academic work. It includes details about the publication, authors, and abstract.

```bibtex
@inbook{PyDriller,
    title = "PyDriller: Python Framework for Mining Software Repositories",
    abstract = "Software repositories contain historical and valuable information about the overall development of software systems. Mining software repositories (MSR) is nowadays considered one of the most interesting growing fields within software engineering. MSR focuses on extracting and analyzing data available in software repositories to uncover interesting, useful, and actionable information about the system. Even though MSR plays an important role in software engineering research, few tools have been created and made public to support developers in extracting information from Git repository. In this paper, we present PyDriller, a Python Framework that eases the process of mining Git. We compare our tool against the state-of-the-art Python Framework GitPython, demonstrating that PyDriller can achieve the same results with, on average, 50% less LOC and significantly lower complexity.URL: https://github.com/ishepard/pydrillerMaterials: https://doi.org/10.5281/zenodo.1327363Pre-print: https://doi.org/10.5281/zenodo.1327411",
    author = "Spadini, Davide and Aniche, MaurÃcio and Bacchelli, Alberto",
    year = "2018",
    doi = "10.1145/3236024.3264598",
    booktitle = "The 26th ACM Joint European Software Engineering Conference and Symposium on the Foundations of Software Engineering (ESEC/FSE)",
}
```

--------------------------------

### Filter Commits by Branch

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Analyzes only those commits that belong to a specified branch. This is useful for focusing on development within a particular line of work.

```python
Repository('path/to/the/repo', only_in_branch='develop').traverse_commits()
```

--------------------------------

### Filter Commits by Author

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Restricts the analysis to commits made by a specific list of authors. The filter checks against the author's username, not their email address.

```python
Repository('path/to/the/repo', only_authors=['John Doe', 'Jane Smith']).traverse_commits()
```

--------------------------------

### Filter Commits by Specific Hashes

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Use `only_commits` to analyze a specific set of commits identified by their hashes. Accepts a list of commit hashes.

```python
Repository('path/to/the/repo', only_commits=['hash1', 'hash2', 'hash3']).traverse_commits()
```

--------------------------------

### Filter Commits by Modified File Types

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Use `only_modifications_with_file_types` to analyze commits where at least one modification occurred in the specified file types. Accepts a list of file extensions.

```python
Repository('path/to/the/repo', only_modifications_with_file_types=['.java']).traverse_commits()
```

--------------------------------

### get_commit(commit_id: str)

Source: https://pydriller.readthedocs.io/en/latest/reference.html

Retrieves a specific commit object by its hash.

```APIDOC
## get_commit(commit_id: str)

### Description
Get the specified commit object.

### Parameters
- **commit_id** (str) - Required - Hash of the commit to analyze.

### Returns
- **Commit** - The requested commit object.
```

--------------------------------

### Filter Commits by Modified File Path

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Analyzes only commits that have modified a specific file. The `filepath` parameter takes the path to the file as a string.

```python
Repository('path/to/the/repo', filepath='src/main.py').traverse_commits()
```

--------------------------------

### Filter Commits by Branch

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Use `only_in_branch` to analyze commits present in a specific branch.

```python
Repository('path/to/the/repo', only_in_branch='branch1').traverse_commits()
```

--------------------------------

### Retrieve Commits Last Modifying Lines

Source: https://pydriller.readthedocs.io/en/latest/_sources/git.rst.txt

Given a commit, this function retrieves all commits that last 'touched' the modified lines of a file within that commit. It can be customized to use 'git hyper-blame' and skip specific commits.

```python
# commit abc modified line 1 of file A
# commit def modified line 2 of file A
# commit ghi modified line 3 of file A
# commit lmn deleted lines 1 and 2 of file A

gr = Git('test-repos/test5')

commit = gr.get_commit('lmn')
buggy_commits = gr.get_commits_last_modified_lines(commit)
print(buggy_commits)      # result: (abc, def)
```

--------------------------------

### Filter Out Merge Commits

Source: https://pydriller.readthedocs.io/en/latest/_sources/repository.rst.txt

Excludes merge commits from the analysis, focusing solely on regular development commits. Set `only_no_merge` to True to enable this filter.

```python
Repository('path/to/the/repo', only_no_merge=True).traverse_commits()
```
Tokens:
Raw