# Git-Narrate User Guide 📖
Welcome to Git-Narrate! This guide will help you get started with turning your project's history into an exciting story.
## What is Git-Narrate?
Imagine your project is like a movie, and every change you make is a scene. Git-Narrate is like a movie director that watches all these scenes and creates a story about how your project was made. It looks at your project's `git` history (the log of all your changes) and writes a narrative about it.
## Key Features
* **Comprehensive Repository Analysis**: Git-Narrate delves into your Git repository to extract detailed information about commits, branches, tags, and contributors.
* **AI-Powered Storytelling**: Leverage the power of AI to transform raw Git data into a rich, engaging, and accurate narrative of your project's development journey.
* **Flexible Output Formats**: Generate your project's story in Markdown, HTML, or plain text, suitable for various uses like documentation, web display, or simple readability.
* **Visual Insights**: Create insightful visualizations, including a commit activity timeline and a contributor activity chart, to better understand your project's evolution and team contributions.
* **Interactive Command-Line Interface**: A user-friendly CLI guides you through the process with clear prompts for repository path, output preferences, and visualization options.
## Getting Started
### 1. Installation
To use Git-Narrate, you first need to install it on your computer. Open your terminal or command prompt and type the following command:
```bash
pip install git-narrate
```
This will download and install Git-Narrate so you can use it from anywhere on your computer.
### 2. Running Git-Narrate
Once installed, you can run Git-Narrate on any of your projects that use `git`.
1. **Navigate to your project folder:**
Open your terminal and go to the folder of the project you want to analyze. For example:
```bash
cd /path/to/your/project
```
2. **Run the command:**
Now, simply run the `git-narrate` command:
```bash
git-narrate
```
The application will then guide you through the process by asking for the following inputs:
* **Path to your Git repository**: You can enter the path to your repository (e.g., `/path/to/your/project`) or simply press Enter to use the current directory (`.`).
* **Output format**: Choose between Markdown, HTML, or plain text for your story.
* **Output file path**: Specify where you want to save the generated story file.
* **Generate visualization charts**: Confirm if you want to create `timeline.png` and `contributors.png` charts.
After you provide these inputs, Git-Narrate will generate the story and any requested visualizations.
## Fun Things You Can Do
Git-Narrate will prompt you for your preferences, allowing you to:
* **Choose Output Format**: Select `html` to generate a story that looks like a webpage (e.g., `git_story.html`).
* **Generate Visualizations**: Opt to create `timeline.png` (commit activity over time) and `contributors.png` (contributor activity) charts.
## For Developers: A Quick Look Under the Hood
If you're a developer and want to contribute to Git-Narrate, here's a quick overview of how it works:
* **`analyzer.py`**: This is the heart of the tool. It uses `GitPython` to read the `.git` folder and extract all the data about commits, branches, tags, and contributors.
* **`narrator.py`**: This module takes the data from the analyzer and turns it into a story. It has different functions to create Markdown, HTML, or plain text stories.
* **`ai_narrator.py`**: This module sends the project data to the Z.ai API and gets back a more detailed story.
* **`visualizer.py`**: This module uses `matplotlib` to create the timeline and contributor charts.
* **`cli.py`**: This file defines the command-line interface using `click`, so you can run `git-narrate` with different options.
### Contributing
We welcome contributions! If you want to help make Git-Narrate even better, please check out our [Contributing Guide](https://github.com/000xs/Git-Narrate/blob/main/CONTRIBUTING.md).
### License
Git-Narrate is licensed under the MIT License. You can find more details in the [LICENSE](https://github.com/000xs/Git-Narrate/blob/main/LICENSE) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/000xs/git-narrate",
"name": "git-narrate",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "git version-control repository-analysis storytelling visualization",
"author": "Sithum Sathsara Rajapakshe | 000x",
"author_email": "SITHUMSS9122@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/80/7e/22f1cf2a6c96023a66124d4405edaa7d5b76ffd19e6049bf04d955488593/git_narrate-1.0.5.tar.gz",
"platform": null,
"description": "# Git-Narrate User Guide \ud83d\udcd6\n\nWelcome to Git-Narrate! This guide will help you get started with turning your project's history into an exciting story.\n\n## What is Git-Narrate?\n\nImagine your project is like a movie, and every change you make is a scene. Git-Narrate is like a movie director that watches all these scenes and creates a story about how your project was made. It looks at your project's `git` history (the log of all your changes) and writes a narrative about it.\n\n## Key Features\n\n* **Comprehensive Repository Analysis**: Git-Narrate delves into your Git repository to extract detailed information about commits, branches, tags, and contributors.\n* **AI-Powered Storytelling**: Leverage the power of AI to transform raw Git data into a rich, engaging, and accurate narrative of your project's development journey.\n* **Flexible Output Formats**: Generate your project's story in Markdown, HTML, or plain text, suitable for various uses like documentation, web display, or simple readability.\n* **Visual Insights**: Create insightful visualizations, including a commit activity timeline and a contributor activity chart, to better understand your project's evolution and team contributions.\n* **Interactive Command-Line Interface**: A user-friendly CLI guides you through the process with clear prompts for repository path, output preferences, and visualization options.\n\n## Getting Started\n\n### 1. Installation\n\nTo use Git-Narrate, you first need to install it on your computer. Open your terminal or command prompt and type the following command:\n\n```bash\npip install git-narrate\n```\n\nThis will download and install Git-Narrate so you can use it from anywhere on your computer.\n\n### 2. Running Git-Narrate\n\nOnce installed, you can run Git-Narrate on any of your projects that use `git`.\n\n1. **Navigate to your project folder:**\n Open your terminal and go to the folder of the project you want to analyze. For example:\n ```bash\n cd /path/to/your/project\n ```\n\n2. **Run the command:**\n Now, simply run the `git-narrate` command:\n ```bash\n git-narrate \n ```\n The application will then guide you through the process by asking for the following inputs:\n * **Path to your Git repository**: You can enter the path to your repository (e.g., `/path/to/your/project`) or simply press Enter to use the current directory (`.`).\n * **Output format**: Choose between Markdown, HTML, or plain text for your story.\n * **Output file path**: Specify where you want to save the generated story file.\n * **Generate visualization charts**: Confirm if you want to create `timeline.png` and `contributors.png` charts.\n\n After you provide these inputs, Git-Narrate will generate the story and any requested visualizations.\n\n## Fun Things You Can Do\n\nGit-Narrate will prompt you for your preferences, allowing you to:\n\n* **Choose Output Format**: Select `html` to generate a story that looks like a webpage (e.g., `git_story.html`).\n* **Generate Visualizations**: Opt to create `timeline.png` (commit activity over time) and `contributors.png` (contributor activity) charts.\n\n \n## For Developers: A Quick Look Under the Hood\n\nIf you're a developer and want to contribute to Git-Narrate, here's a quick overview of how it works:\n\n* **`analyzer.py`**: This is the heart of the tool. It uses `GitPython` to read the `.git` folder and extract all the data about commits, branches, tags, and contributors.\n* **`narrator.py`**: This module takes the data from the analyzer and turns it into a story. It has different functions to create Markdown, HTML, or plain text stories.\n* **`ai_narrator.py`**: This module sends the project data to the Z.ai API and gets back a more detailed story.\n* **`visualizer.py`**: This module uses `matplotlib` to create the timeline and contributor charts.\n* **`cli.py`**: This file defines the command-line interface using `click`, so you can run `git-narrate` with different options.\n\n### Contributing\n\nWe welcome contributions! If you want to help make Git-Narrate even better, please check out our [Contributing Guide](https://github.com/000xs/Git-Narrate/blob/main/CONTRIBUTING.md).\n\n### License\n\nGit-Narrate is licensed under the MIT License. You can find more details in the [LICENSE](https://github.com/000xs/Git-Narrate/blob/main/LICENSE) file.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The Repository Storyteller - Analyze git repos and generate development narratives",
"version": "1.0.5",
"project_urls": {
"Bug Tracker": "https://github.com/000xs/git-narrate/issues",
"Documentation": "https://github.com/000xs/git-narrate/wiki",
"Homepage": "https://github.com/000xs/git-narrate"
},
"split_keywords": [
"git",
"version-control",
"repository-analysis",
"storytelling",
"visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3d432525605cddfb8147149e30d7ffcacb2d7209daf814e7be09dc50babf2b49",
"md5": "e4fcbd8e961a7018536cb03026732468",
"sha256": "8ae6f4a6ae450a2624d86cabad9bfea70f6793b4be3558990d85d49b92b77dc1"
},
"downloads": -1,
"filename": "git_narrate-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4fcbd8e961a7018536cb03026732468",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12050,
"upload_time": "2025-08-11T11:27:02",
"upload_time_iso_8601": "2025-08-11T11:27:02.628616Z",
"url": "https://files.pythonhosted.org/packages/3d/43/2525605cddfb8147149e30d7ffcacb2d7209daf814e7be09dc50babf2b49/git_narrate-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "807e22f1cf2a6c96023a66124d4405edaa7d5b76ffd19e6049bf04d955488593",
"md5": "464193e9e6e4334cd2ebd8ead70bcdd1",
"sha256": "b6400742f1cca572511771f458e356b3f335f47897a8ad37541a919e993a9171"
},
"downloads": -1,
"filename": "git_narrate-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "464193e9e6e4334cd2ebd8ead70bcdd1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12789,
"upload_time": "2025-08-11T11:27:03",
"upload_time_iso_8601": "2025-08-11T11:27:03.430160Z",
"url": "https://files.pythonhosted.org/packages/80/7e/22f1cf2a6c96023a66124d4405edaa7d5b76ffd19e6049bf04d955488593/git_narrate-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 11:27:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "000xs",
"github_project": "git-narrate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": [
[
"==",
"8.2.1"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"14.1.0"
]
]
},
{
"name": "GitPython",
"specs": [
[
"==",
"3.1.44"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"==",
"3.10.5"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.3.2"
]
]
},
{
"name": "openai",
"specs": [
[
"==",
"1.99.1"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "questionary",
"specs": [
[
"==",
"2.1.0"
]
]
},
{
"name": "pyfiglet",
"specs": [
[
"==",
"1.0.3"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.28.0"
]
]
},
{
"name": "build",
"specs": []
},
{
"name": "markdown2",
"specs": []
}
],
"lcname": "git-narrate"
}
JSON
