Skip to content

Commit f33d28e

Browse files
author
Coding With Shawn
committed
final README version
1 parent 466aad6 commit f33d28e

File tree

1 file changed

+375
-0
lines changed

1 file changed

+375
-0
lines changed

‎README.md‎

Lines changed: 375 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,375 @@
1+
<p align="center"><h1 align="center">GITANALYZER</h1></p>
2+
<p align="center">
3+
<em>A powerful Python library for mining and analyzing Git repositories</em>
4+
</p>
5+
<p align="center">
6+
<img src="https://img.shields.io/github/license/codingwithshawnyt/GitAnalyzer?style=default&logo=opensourceinitiative&logoColor=white&color=0080ff" alt="license">
7+
<img src="https://img.shields.io/github/last-commit/codingwithshawnyt/GitAnalyzer?style=default&logo=git&logoColor=white&color=0080ff" alt="last-commit">
8+
<img src="https://img.shields.io/github/languages/top/codingwithshawnyt/GitAnalyzer?style=default&color=0080ff" alt="repo-top-language">
9+
<img src="https://img.shields.io/github/languages/count/codingwithshawnyt/GitAnalyzer?style=default&color=0080ff" alt="repo-language-count">
10+
</p>
11+
<br>
12+
13+
## 🔗 Table of Contents
14+
15+
- [📍 Overview](#-overview)
16+
- [👾 Features](#-features)
17+
- [📁 Project Structure](#-project-structure)
18+
- [📂 Project Index](#-project-index)
19+
- [🚀 Getting Started](#-getting-started)
20+
- [☑️ Prerequisites](#-prerequisites)
21+
- [⚙️ Installation](#-installation)
22+
- [🤖 Usage](#🤖-usage)
23+
- [🧪 Testing](#🧪-testing)
24+
- [📌 Project Roadmap](#-project-roadmap)
25+
- [🔰 Contributing](#-contributing)
26+
- [🎗 License](#-license)
27+
- [🙌 Acknowledgments](#-acknowledgments)
28+
29+
---
30+
31+
## 📍 Overview
32+
33+
GitAnalyzer is a Python library for mining and analyzing Git repositories. It provides a powerful interface for extracting detailed information about commits, developers, and code changes. The tool supports both local and remote repositories, with features including:
34+
35+
- Commit history traversal and filtering
36+
- Code change analysis
37+
- Developer contribution tracking
38+
- Process metrics calculation
39+
- Support for multiple repository analysis
40+
41+
---
42+
43+
## 👾 Features
44+
45+
- **Flexible Repository Access**: Analyze both local and remote Git repositories
46+
- **Comprehensive Commit Analysis**: Extract detailed information about commits, including:
47+
- Author and committer details
48+
- Modified files and their changes
49+
- Code churn metrics
50+
- Commit relationships
51+
- **Developer Analytics**: Track developer contributions and experience
52+
- **Process Metrics**: Calculate various software process metrics
53+
- **Multiple Repository Support**: Analyze multiple repositories in sequence
54+
- **Mailmap Support**: Proper handling of author mappings via .mailmap files
55+
- **Configurable Filters**: Filter commits by:
56+
- Date ranges
57+
- Commit hashes
58+
- Tags
59+
- File types
60+
- Authors
61+
62+
---
63+
64+
## 📁 Project Structure
65+
66+
```sh
67+
└── GitAnalyzer/
68+
├── LICENSE
69+
├── Makefile # Build automation configuration
70+
├── dev-requirements.txt # Development dependencies
71+
├── docs # Documentation directory
72+
│ ├── Makefile # Documentation build configuration
73+
│ ├── commit.rst # Commit analysis documentation
74+
│ ├── conf.py # Sphinx configuration
75+
│ ├── deltamaintainability.rst # Maintainability metrics docs
76+
│ ├── git.rst # Git interface documentation
77+
│ ├── index.rst # Documentation index
78+
│ ├── intro.rst # Introduction guide
79+
│ ├── modifiedfile.rst # File modification docs
80+
│ ├── processmetrics.rst # Process metrics documentation
81+
│ ├── reference.rst # API reference
82+
│ ├── repository.rst # Repository handling docs
83+
│ ├── requirements.txt # Documentation dependencies
84+
│ └── tutorial.rst # Usage tutorial
85+
├── gitanalyzer # Main package directory
86+
│ ├── domain # Core domain models
87+
│ ├── git.py # Git interface implementation
88+
│ ├── metrics # Analysis metrics implementations
89+
│ ├── repository.py # Repository management
90+
│ └── utils # Utility functions and helpers
91+
├── pytest.ini # PyTest configuration
92+
├── requirements.txt # Core dependencies
93+
├── setup.py # Package installation setup
94+
├── test-requirements.txt # Testing dependencies
95+
└── tests # Test suite directory
96+
├── integration # Integration tests
97+
├── metrics # Metrics tests
98+
├── test_*.py # Unit test files
99+
```
100+
101+
### 📂 Project Index
102+
<details open>
103+
<summary><b><code>GITANALYZER/</code></b></summary>
104+
<details>
105+
<summary><b>__root__</b></summary>
106+
<blockquote>
107+
<table>
108+
<tr>
109+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/dev-requirements.txt'>dev-requirements.txt</a></b></td>
110+
<td><code>Development dependencies including mypy, flake8, and pytest-cov</code></td>
111+
</tr>
112+
<tr>
113+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/pytest.ini'>pytest.ini</a></b></td>
114+
<td><code>PyTest configuration for test suite</code></td>
115+
</tr>
116+
<tr>
117+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/test-requirements.txt'>test-requirements.txt</a></b></td>
118+
<td><code>Testing-specific dependencies</code></td>
119+
</tr>
120+
<tr>
121+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/requirements.txt'>requirements.txt</a></b></td>
122+
<td><code>Core package dependencies including GitPython and pytz</code></td>
123+
</tr>
124+
<tr>
125+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/Makefile'>Makefile</a></b></td>
126+
<td><code>Build and development automation tasks</code></td>
127+
</tr>
128+
<tr>
129+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/setup.py'>setup.py</a></b></td>
130+
<td><code>Package installation and distribution configuration</code></td>
131+
</tr>
132+
</table>
133+
</blockquote>
134+
</details>
135+
<details>
136+
<summary><b>gitanalyzer</b></summary>
137+
<blockquote>
138+
<table>
139+
<tr>
140+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/git.py'>git.py</a></b></td>
141+
<td><code>Core Git interaction and repository management</code></td>
142+
</tr>
143+
<tr>
144+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/repository.py'>repository.py</a></b></td>
145+
<td><code>High-level repository analysis interface</code></td>
146+
</tr>
147+
</table>
148+
<details>
149+
<summary><b>metrics</b></summary>
150+
<blockquote>
151+
<details>
152+
<summary><b>process</b></summary>
153+
<blockquote>
154+
<table>
155+
<tr>
156+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/metrics/process/commits_count.py'>commits_count.py</a></b></td>
157+
<td><code>Commit frequency analysis</code></td>
158+
</tr>
159+
<tr>
160+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/metrics/process/change_set.py'>change_set.py</a></b></td>
161+
<td><code>Change set size metrics</code></td>
162+
</tr>
163+
<tr>
164+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/metrics/process/contributors_count.py'>contributors_count.py</a></b></td>
165+
<td><code>Contributor participation metrics</code></td>
166+
</tr>
167+
<tr>
168+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/metrics/process/contributors_experience.py'>contributors_experience.py</a></b></td>
169+
<td><code>Developer experience analysis</code></td>
170+
</tr>
171+
<tr>
172+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/metrics/process/lines_count.py'>lines_count.py</a></b></td>
173+
<td><code>Code line modification metrics</code></td>
174+
</tr>
175+
<tr>
176+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/metrics/process/hunks_count.py'>hunks_count.py</a></b></td>
177+
<td><code>Code change block analysis</code></td>
178+
</tr>
179+
<tr>
180+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/metrics/process/process_metric.py'>process_metric.py</a></b></td>
181+
<td><code>Base process metric implementation</code></td>
182+
</tr>
183+
<tr>
184+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/metrics/process/history_complexity.py'>history_complexity.py</a></b></td>
185+
<td><code>Repository history complexity metrics</code></td>
186+
</tr>
187+
<tr>
188+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/metrics/process/code_churn.py'>code_churn.py</a></b></td>
189+
<td><code>Code churn and volatility metrics</code></td>
190+
</tr>
191+
</table>
192+
</blockquote>
193+
</details>
194+
</blockquote>
195+
</details>
196+
<details>
197+
<summary><b>utils</b></summary>
198+
<blockquote>
199+
<table>
200+
<tr>
201+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/utils/mailmap.py'>mailmap.py</a></b></td>
202+
<td><code>Git mailmap handling utilities</code></td>
203+
</tr>
204+
<tr>
205+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/utils/check_git_version.py'>check_git_version.py</a></b></td>
206+
<td><code>Git version compatibility checker</code></td>
207+
</tr>
208+
<tr>
209+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/utils/conf.py'>conf.py</a></b></td>
210+
<td><code>Configuration management utilities</code></td>
211+
</tr>
212+
</table>
213+
</blockquote>
214+
</details>
215+
<details>
216+
<summary><b>domain</b></summary>
217+
<blockquote>
218+
<table>
219+
<tr>
220+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/domain/commit.py'>commit.py</a></b></td>
221+
<td><code>Commit entity model and analysis</code></td>
222+
</tr>
223+
<tr>
224+
<td><b><a href='https://github.com/codingwithshawnyt/GitAnalyzer/blob/master/gitanalyzer/domain/developer.py'>developer.py</a></b></td>
225+
<td><code>Developer entity model and tracking</code></td>
226+
</tr>
227+
</table>
228+
</blockquote>
229+
</details>
230+
</blockquote>
231+
</details>
232+
</details>
233+
234+
---
235+
## 🚀 Getting Started
236+
237+
### ☑️ Prerequisites
238+
239+
Before getting started with GitAnalyzer, ensure your runtime environment meets the following requirements:
240+
241+
- **Python:** Version 3.8 or higher
242+
- **Git:** Any recent version
243+
- **Operating System:** Linux, macOS, or Windows
244+
- **Package Manager:** pip
245+
246+
247+
### ⚙️ Installation
248+
249+
Install GitAnalyzer using one of the following methods:
250+
251+
**Build from source:**
252+
253+
1. Clone the GitAnalyzer repository:
254+
```sh
255+
❯ git clone https://github.com/codingwithshawnyt/GitAnalyzer
256+
```
257+
258+
2. Navigate to the project directory:
259+
```sh
260+
❯ cd GitAnalyzer
261+
```
262+
263+
3. Install the project dependencies:
264+
265+
**Using `pip`** &nbsp; [<img align="center" src="https://img.shields.io/badge/Pip-3776AB.svg?style=default&logo=pypi&logoColor=white" />](https://pypi.org/project/pip/)
266+
267+
```sh
268+
❯ pip install -r requirements.txt -r dev-requirements.txt -r test-requirements.txt
269+
```
270+
271+
### 🤖 Usage
272+
273+
Here's a basic example of using GitAnalyzer:
274+
275+
```python
276+
from gitanalyzer import Repository
277+
278+
# Initialize repository (local or remote)
279+
repo = Repository('path/to/repository')
280+
281+
# Traverse commits
282+
for commit in repo.traverse_commits():
283+
print(f'Commit: {commit.hash}')
284+
print(f'Author: {commit.author.name}')
285+
print(f'Date: {commit.author_date}')
286+
287+
# Access modified files
288+
for modification in commit.modified_files:
289+
print(f'Modified file: {modification.filename}')
290+
print(f'Changes: +{modification.added_lines}, -{modification.deleted_lines}')
291+
```
292+
293+
### 🧪 Testing
294+
295+
Run the test suite using the following command:
296+
297+
```sh
298+
❯ pytest
299+
```
300+
301+
For coverage report:
302+
303+
```sh
304+
❯ pytest --cov=gitanalyzer
305+
```
306+
307+
---
308+
## 📌 Project Roadmap
309+
310+
- [X] **Core Functionality**: Basic commit traversal and analysis
311+
- [X] **Process Metrics**: Implementation of various process metrics
312+
- [X] **Multiple Repository Support**: Ability to analyze multiple repositories
313+
- [X] **Documentation**: Comprehensive documentation with Sphinx
314+
- [ ] **Additional Metrics**: Implementation of more advanced metrics
315+
- [ ] **Performance Optimization**: Improve analysis speed for large repositories
316+
317+
---
318+
319+
## 🔰 Contributing
320+
321+
- **💬 [Join the Discussions](https://github.com/codingwithshawnyt/GitAnalyzer/discussions)**: Share your insights, provide feedback, or ask questions.
322+
- **🐛 [Report Issues](https://github.com/codingwithshawnyt/GitAnalyzer/issues)**: Submit bugs found or log feature requests for the `GitAnalyzer` project.
323+
- **💡 [Submit Pull Requests](https://github.com/codingwithshawnyt/GitAnalyzer/pulls)**: Review open PRs, and submit your own PRs.
324+
325+
<details closed>
326+
<summary>Contributing Guidelines</summary>
327+
328+
1. **Fork the Repository**: Start by forking the project repository to your GitHub account.
329+
2. **Clone Locally**: Clone the forked repository to your local machine using a git client.
330+
```sh
331+
git clone https://github.com/codingwithshawnyt/GitAnalyzer
332+
```
333+
3. **Create a New Branch**: Always work on a new branch, giving it a descriptive name.
334+
```sh
335+
git checkout -b new-feature-x
336+
```
337+
4. **Make Your Changes**: Develop and test your changes locally.
338+
5. **Commit Your Changes**: Commit with a clear message describing your updates.
339+
```sh
340+
git commit -m 'Implemented new feature x.'
341+
```
342+
6. **Push to GitHub**: Push the changes to your forked repository.
343+
```sh
344+
git push origin new-feature-x
345+
```
346+
7. **Submit a Pull Request**: Create a PR against the original project repository. Clearly describe the changes and their motivations.
347+
8. **Review**: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!
348+
</details>
349+
350+
<details closed>
351+
<summary>Contributor Graph</summary>
352+
<br>
353+
<p align="left">
354+
<a href="https://github.com/codingwithshawnyt/GitAnalyzer/graphs/contributors">
355+
<img src="https://contrib.rocks/image?repo=codingwithshawnyt/GitAnalyzer">
356+
</a>
357+
</p>
358+
</details>
359+
360+
---
361+
362+
## 🎗 License
363+
364+
This project is protected under the [Apache License 2.0](https://choosealicense.com/licenses/apache-2.0/) License. For more details, refer to the [LICENSE](LICENSE) file.
365+
366+
---
367+
368+
## 🙌 Acknowledgments
369+
370+
- **GitPython**: Core Git interaction functionality
371+
- **Sphinx**: Documentation generation
372+
- **pytest**: Testing framework
373+
- All contributors who have helped improve GitAnalyzer
374+
375+
---

0 commit comments

Comments
 (0)