Skip to content

Available Functions and Documentation

This page provides an overview of all the available functions and their documentation in our project.

Contributors Plugin

display_contributors_info(repo_path)

Generates a Dash layout component showing the contributors and their commit counts.

Parameters:

Name Type Description Default
repo_path

The file system path to the git repository.

 required

Returns:

Type Description

A Dash HTML component with the list of contributors or an error message.
Source code in insight_git/plugins/contributors_info.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def display_contributors_info(repo_path):
    """
    Generates a Dash layout component showing the contributors and their commit counts.

    Args:
        repo_path: The file system path to the git repository.

    Returns:
        A Dash HTML component with the list of contributors or an error message.
    """
    contributors_data = extract_contributors(repo_path)
    if "error" in contributors_data:
        return dbc.Alert(f"Error: {contributors_data['error']}", color="danger")

    layout = html.Div(
        [
            dcc.Store(id="contributors-store", data=contributors_data),
            dcc.Store(
                id="updated-contributors-store"
            ),  # Store to keep the updated contributors' data
            html.H5("Contributors", className="mb-3"),
            dbc.ListGroup(
                id="contributors-list",
                children=[
                    dbc.ListGroupItem(f"{contributor}: {count}")
                    for contributor, count in contributors_data.items()
                ],
                className="mb-4",
            ),
            dbc.Row(
                [
                    dbc.Col(
                        dbc.Input(
                            id="original-name", placeholder="Original Name or Username"
                        ),
                        width=4,
                    ),
                    dbc.Col(
                        dbc.Input(id="unified-name", placeholder="Unified Name"),
                        width=4,
                    ),
                    dbc.Col(
                        dbc.Button(
                            "Unify", id="unify-btn", color="success", className="me-1"
                        ),
                        width=4,
                    ),
                ]
            ),
        ],
        style={"maxWidth": "720px", "margin": "0 auto"},
    )

    return layout

display_updated_contributors(updated_data)

Updates the displayed list of contributors based on the updated data.

Parameters:

Name Type Description Default
updated_data

The updated contributors' data from the updated-contributors-store.

 required

Returns:

Type Description

A list of Dash components representing the updated contributors.
Source code in insight_git/plugins/contributors_info.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
@callback(
    Output("contributors-list", "children"),
    [Input("updated-contributors-store", "data")],
)
def display_updated_contributors(updated_data):
    """
    Updates the displayed list of contributors based on the updated data.

    Args:
        updated_data: The updated contributors' data from the updated-contributors-store.

    Returns:
        A list of Dash components representing the updated contributors.
    """
    if updated_data is None:
        raise PreventUpdate

    updated_contributors = [
        dbc.ListGroupItem(f"{contributor}: {count}")
        for contributor, count in updated_data.items()
    ]
    return updated_contributors

extract_contributors(repo_path)

Extracts the contributors and their commit counts from a git repository.

Parameters:

Name Type Description Default
repo_path

The file system path to the git repository.

 required

Returns:

Type Description

A Counter object with contributors' names as keys and their commit counts as values.

If an error occurs, returns a dict with an 'error' key and the error message.
Source code in insight_git/plugins/contributors_info.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
def extract_contributors(repo_path):
    """
    Extracts the contributors and their commit counts from a git repository.

    Args:
        repo_path: The file system path to the git repository.

    Returns:
        A Counter object with contributors' names as keys and their commit counts as values.
        If an error occurs, returns a dict with an 'error' key and the error message.
    """
    try:
        repo = Repo(repo_path)
        commits = list(repo.iter_commits())
        contributors = Counter(commit.author.name for commit in commits)
        return contributors
    except Exception as e:
        return {"error": str(e)}

update_contributors_data(n_clicks, initial_data, updated_data, original_name, unified_name)

Updates the contributors' data by unifying names based on user input.

Parameters:

Name Type Description Default
n_clicks

Number of times the unify button has been clicked.

 required
initial_data

The initial data from the contributors-store.

 required
updated_data

The potentially updated data from the updated-contributors-store.

 required
original_name

The original name to be replaced.

 required
unified_name

The new name that replaces the original.

 required

Returns:

Type Description

The updated contributors' data.
Source code in insight_git/plugins/contributors_info.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
@callback(
    Output("updated-contributors-store", "data"),
    Input("unify-btn", "n_clicks"),
    [
        State("contributors-store", "data"),
        State("updated-contributors-store", "data"),
        State("original-name", "value"),
        State("unified-name", "value"),
    ],
    prevent_initial_call=True,
)
def update_contributors_data(
    n_clicks, initial_data, updated_data, original_name, unified_name
):
    """
    Updates the contributors' data by unifying names based on user input.

    Args:
        n_clicks: Number of times the unify button has been clicked.
        initial_data: The initial data from the contributors-store.
        updated_data: The potentially updated data from the updated-contributors-store.
        original_name: The original name to be replaced.
        unified_name: The new name that replaces the original.

    Returns:
        The updated contributors' data.
    """
    if not original_name or not unified_name:
        raise PreventUpdate

    contributors_data = updated_data if updated_data is not None else initial_data

    if original_name in contributors_data:
        contributors_data[unified_name] = contributors_data.get(
            unified_name, 0
        ) + contributors_data.pop(original_name, 0)

    return contributors_data

Documents functions related to extracting and displaying contributor information from a Git repository.

Git Statistics

display_git_statistics(repo_path)

Creates a Dash HTML component displaying general Git statistics for a repository including branch information.

This function uses the extract_git_stats function to gather statistics about a repository's commit history and branches, then constructs a Dash HTML component to visually present these statistics.

Parameters:

Name Type Description Default
repo_path str

The file system path to the local Git repository.

 required

Returns:

Type Description

dash.html.Div: A Dash HTML component containing the visual representation of the repository's general statistics. If an error occurs during statistics extraction, the component will display the error message.
Source code in insight_git/plugins/git_statistics.py 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def display_git_statistics(repo_path):
    """
    Creates a Dash HTML component displaying general Git statistics for a repository including branch information.

    This function uses the `extract_git_stats` function to gather statistics about a repository's commit history and branches,
    then constructs a Dash HTML component to visually present these statistics.

    Args:
        repo_path (str): The file system path to the local Git repository.

    Returns:
        dash.html.Div: A Dash HTML component containing the visual representation of the repository's general statistics.
                       If an error occurs during statistics extraction, the component will display the error message.
    """
    stats = extract_git_stats(repo_path)
    if "error" in stats:
        return html.Div(f"Error: {stats['error']}")

    branch_list = html.Ul(
        [
            html.Li(
                f"{branch['name']}: Last commit {branch['last_commit']} ({branch['last_commit_message']!r})"
            )
            for branch in stats["branch_details"]
        ]
    )

    return html.Div(
        [
            html.H5("General Statistics"),
            html.Ul(
                [
                    html.Li(f"Total Commits: {stats['total_commits']}"),
                    html.Li(f"First Commit Date: {stats['first_commit_date']}"),
                    html.Li(f"Last Commit Date: {stats['last_commit_date']}"),
                    html.Li(f"Total Lines Added: {stats['total_lines_added']}"),
                    html.Li(f"Total Lines Deleted: {stats['total_lines_deleted']}"),
                    html.Li(f"Total Lines Changed: {stats['total_lines_changed']}"),
                    html.Li(
                        f"Average Lines per Commit: {stats['average_lines_per_commit']:.2f}"
                    ),
                    html.Li(f"Total Branches: {stats['total_branches']}"),
                ]
            ),
            html.H6("Branch Details"),
            branch_list,
        ],
        className="mt-4",
    )

extract_git_stats(repo_path)

Extracts comprehensive Git statistics from a repository's commit history including branch details.

This function collects data on the number of commits, commit dates, total lines added and deleted across all commits, and computes the average lines changed per commit. It also provides dates for the first and last commit and detailed information on each branch.

Parameters:

Name Type Description Default
repo_path str

The file system path to the local Git repository.

 required

Returns:

Name Type Description
dict

A dictionary containing statistics about the repository including the total number of commits, a list of commit dates, the first and last commit date, total and average lines changed per commit, total branches, and details of each branch. If an error occurs, returns a dictionary with an 'error' key containing the error message.
Source code in insight_git/plugins/git_statistics.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def extract_git_stats(repo_path):
    """
    Extracts comprehensive Git statistics from a repository's commit history including branch details.

    This function collects data on the number of commits, commit dates, total lines added and deleted across all commits,
    and computes the average lines changed per commit. It also provides dates for the first and last commit and detailed
    information on each branch.

    Args:
        repo_path (str): The file system path to the local Git repository.

    Returns:
        dict: A dictionary containing statistics about the repository including the total number of commits,
              a list of commit dates, the first and last commit date, total and average lines changed per commit,
              total branches, and details of each branch.
              If an error occurs, returns a dictionary with an 'error' key containing the error message.
    """
    try:
        repo = Repo(repo_path)
        commits = list(repo.iter_commits())

        # Collect commit dates
        commit_dates = [commit.committed_datetime for commit in commits]
        total_lines_added = sum(commit.stats.total["insertions"] for commit in commits)
        total_lines_deleted = sum(commit.stats.total["deletions"] for commit in commits)
        total_lines_changed = total_lines_added + total_lines_deleted
        average_lines_per_commit = (
            (total_lines_changed / len(commits)) if commits else 0
        )

        # Dates for the first and last commit
        first_commit_date = commit_dates[-1] if commits else None
        last_commit_date = commit_dates[0] if commits else None

        # Branch details
        branches = repo.branches
        branch_details = [
            {
                "name": branch.name,
                "last_commit": branch.commit.hexsha,
                "last_commit_message": branch.commit.message.strip(),
            }
            for branch in branches
        ]

        return {
            "total_commits": len(commits),
            "commit_dates": commit_dates,
            "first_commit_date": first_commit_date,
            "last_commit_date": last_commit_date,
            "total_lines_added": total_lines_added,
            "total_lines_deleted": total_lines_deleted,
            "total_lines_changed": total_lines_changed,
            "average_lines_per_commit": average_lines_per_commit,
            "total_branches": len(branches),
            "branch_details": branch_details,
        }

    except Exception as e:
        logging.error(f"Error extracting git statistics: {e}")
        return {"error": str(e)}

Details the functionalities for gathering and displaying various statistics from a Git repository.

Commit Graph

display_commit_graph(repo_path)

Generates and displays a graph of commit activity over time for a Git repository using Dash and Plotly.

This function first extracts commit dates and then uses Pandas to organize these dates into a DataFrame for easy plotting with Plotly. The resulting graph shows the number of commits per day.

Parameters:

Name Type Description Default
repo_path str

The file system path to the local Git repository.

 required

Returns:

Type Description

dash.dcc.Graph: A Dash graph component that visually represents commit activity over time.

If an error occurs in extracting commit dates, this function raises PreventUpdate to stop the Dash app from updating.

Raises:

Type Description
PreventUpdate

If there is an error in extracting commit dates, indicating that the graph cannot be displayed.
Source code in insight_git/plugins/commit_graph.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def display_commit_graph(repo_path):
    """
    Generates and displays a graph of commit activity over time for a Git repository using Dash and Plotly.

    This function first extracts commit dates and then uses Pandas to organize these dates into a DataFrame
    for easy plotting with Plotly. The resulting graph shows the number of commits per day.

    Args:
        repo_path (str): The file system path to the local Git repository.

    Returns:
        dash.dcc.Graph: A Dash graph component that visually represents commit activity over time.
        If an error occurs in extracting commit dates, this function raises PreventUpdate to stop the Dash app from updating.

    Raises:
        PreventUpdate: If there is an error in extracting commit dates, indicating that the graph cannot be displayed.
    """

    commit_dates = extract_commit_dates(repo_path)
    if "error" in commit_dates:
        raise PreventUpdate
    df = pd.DataFrame(
        {
            "Commit Date": pd.to_datetime(commit_dates, utc=True),
            "Commit Count": 1,
        }
    )
    df["Commit Date"] = df["Commit Date"].dt.tz_convert(None)
    df["Commit Date"] = df["Commit Date"].dt.date

    df_group = df.groupby("Commit Date").count().reset_index()

    fig = go.Figure(
        data=[
            go.Scatter(
                x=df_group["Commit Date"],
                y=df_group["Commit Count"],
                mode="lines+markers",
            )
        ]
    )
    fig.update_layout(
        title="Commit Activity Over Time",
        xaxis_title="Date",
        yaxis_title="Number of Commits",
    )

    return dcc.Graph(figure=fig)

extract_commit_dates(repo_path)

Extracts commit dates from a local Git repository to analyze commit activity over time.

This function iterates over all commits in the specified repository, collecting the datetime for each commit.

Parameters:

Name Type Description Default
repo_path str

The file system path to the local Git repository.

 required

Returns:

Name Type Description
list

A list of datetime objects representing the commit dates.

Returns a dictionary with an 'error' key if an exception occurs.
Source code in insight_git/plugins/commit_graph.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
def extract_commit_dates(repo_path):
    """
    Extracts commit dates from a local Git repository to analyze commit activity over time.

    This function iterates over all commits in the specified repository, collecting the datetime for each commit.

    Args:
        repo_path (str): The file system path to the local Git repository.

    Returns:
        list: A list of datetime objects representing the commit dates.
        Returns a dictionary with an 'error' key if an exception occurs.
    """

    try:
        repo = Repo(repo_path)
        commits = list(repo.iter_commits())
        commit_dates = [commit.committed_datetime for commit in commits]
        return commit_dates
    except Exception as e:
        return {"error": str(e)}

Describes how to generate and display graphical representations of commit histories.

Commit Type

categorize_commit_type(commit_message)

Categorizes a commit message into predefined types such as Bug Fix, Feature, Documentation, or Other.

This function analyzes the commit message for keywords that indicate its type.

Parameters:

Name Type Description Default
commit_message str

The commit message to categorize.

 required

Returns:

Name Type Description
str

The category of the commit based on its message.
Source code in insight_git/plugins/commit_type.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def categorize_commit_type(commit_message):
    """
    Categorizes a commit message into predefined types such as Bug Fix, Feature, Documentation, or Other.

    This function analyzes the commit message for keywords that indicate its type.

    Args:
        commit_message (str): The commit message to categorize.

    Returns:
        str: The category of the commit based on its message.
    """

    commit_message = commit_message.lower()
    if "fix" in commit_message or "bug" in commit_message:
        return "Bug Fix"
    elif "feature" in commit_message or "add" in commit_message:
        return "Feature"
    elif "doc" in commit_message or "readme" in commit_message:
        return "Documentation"
    else:
        return "Other"

extract_commit_types(repo_path)

Extracts and counts the types of commits in a local Git repository based on commit messages.

This function iterates over all commits in the specified repository, categorizing each commit according to predefined types (e.g., Bug Fix, Feature, Documentation) based on its message.

Parameters:

Name Type Description Default
repo_path str

The file system path to the local Git repository.

 required

Returns:

Type Description

collections.Counter: A Counter object mapping commit types to their frequencies.

Returns a dictionary with an 'error' key if an exception occurs.
Source code in insight_git/plugins/commit_type.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
def extract_commit_types(repo_path):
    """
    Extracts and counts the types of commits in a local Git repository based on commit messages.

    This function iterates over all commits in the specified repository, categorizing each commit
    according to predefined types (e.g., Bug Fix, Feature, Documentation) based on its message.

    Args:
        repo_path (str): The file system path to the local Git repository.

    Returns:
        collections.Counter: A Counter object mapping commit types to their frequencies.
        Returns a dictionary with an 'error' key if an exception occurs.
    """

    try:
        repo = Repo(repo_path)
        commits = list(repo.iter_commits())
        commit_types = Counter(
            categorize_commit_type(commit.message) for commit in commits
        )
        return commit_types
    except Exception as e:
        return {"error": str(e)}

Explains the methods used to categorize and display commit types based on commit messages.