| Name | git2md JSON |
| Version |
1.1.7
JSON |
| download |
| home_page | https://github.com/xpos587/git2md |
| Summary | Convert Git repository contents to Markdown format |
| upload_time | 2025-02-12 17:48:50 |
| maintainer | None |
| docs_url | None |
| author | Michael |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🔄 git2md
🚀 A powerful command-line tool for converting Git repository contents into Markdown format.
This tool is perfect for developers and documentation specialists who need to create
structured Markdown files based on repository contents, including directory trees and file contents.
Read README in Russian [here](https://github.com/Xpos587/git2md/blob/main/README_RU.md)
---
## ✨ Features
- **🌳 Repository Directory Tree Generation**: outputs repository structure in `tree` block format.
- **📝 File to Markdown Conversion**:
- Supports syntax highlighting for code files.
- ~~Converts Jupyter Notebook (`.ipynb`) and PDF (`.pdf`) to Markdown.~~
- **🎯 Support for `.gitignore`, `.globalignore` and `.mdignore` for local projects**:
- Automatically excludes files/directories specified in `.gitignore`, `.globalignore` or `.mdignore`.
- **🔍 Custom Exclusion Patterns**: use regular expressions to exclude specific files or directories.
- **🗑️ Skip Empty Files**: ignores files without content.
- **📋 Copy Results to Clipboard**: simplifies using generated Markdown.
---
## 🎬 Demonstration
Below is a demonstration of how `git2md` works:
---
## 📋 Requirements
- **🐍 Python 3.9 or newer**
- **🐧 ~~Linux Operating System~~ Now supports Windows, MacOS, Linux (X11 and Wayland)**
- **📦 Dependencies**:
- `pathspec` (for `.gitignore`, `.mdignore`, `.globalignore` support)
- ~~`nbconvert` (for Jupyter Notebook conversion)~~ (support temporarily limited)
- ~~`PyMuPDF4LLM` (for PDF conversion)~~ (support discontinued, will be replaced with better alternatives)
- `wl-copy/xsel/xclip` (optional, Linux-only for clipboard functionality)
---
## 📥 Installation
### 📦 Install via PyPI
You can install `git2md` directly through PyPI using pip:
```bash
pip install git2md
```
### 🏗️ Install via AUR (Arch Linux)
For Arch Linux users, the package is available in AUR as [python-git2md](https://aur.archlinux.org/packages/python-git2md). It can be installed using AUR helpers like `paru` or `yay`:
```bash
paru -S python-git2md
```
### 🔨 Install from Source
1. Clone the repository:
```bash
git clone https://github.com/xpos587/git2md.git
cd git2md
```
2. Build and install:
```bash
python setup.py build
pip install .
```
---
## 🚀 Usage
### 💻 Basic Command
```bash
git2md [path] [options]
```
If path is not specified, the current directory will be used.
### ⚙️ Options
| Option | Description |
| ---------------- | --------------------------------------------------------------- |
| `path` | Path to project directory or Git file (default: current folder) |
| `-o`, `--output` | Path to save generated Markdown |
| `-c`, `--copy` | Copy result to clipboard |
| `--ignore` | List of patterns to exclude files or directories |
---
## 📝 Examples
### 📂 Generate Markdown for Entire Repository
```bash
git2md /path/to/repo -o output.md
```
### 🔍 Exclude Specific Files Using Patterns
```bash
git2md --ignore "./assets/style-*.css" "*.log" "*.tmp" -o output.md
```
### 🗑️ Copy Result to Clipboard
```bash
git2md --copy
```
---
## 📄 Output Format
### 🌳 Directory Tree
The directory tree is included as a code block with language identifier `tree`. For example:
```tree
src/
├── main.py
├── utils/
│ ├── helper.py
│ └── __init__.py
└── README.md
```
### 📑 File Contents
Each file is included with its relative path in the header, followed by its contents in a code block.
#### 🐍 Example for Python File (`main.py`)
````markdown
# File: src/main.py
```
print("Hello, world!")
```
# End of file: src/main.py
````
#### 📓 Example for Jupyter Notebook (`notebook.ipynb`)
Content is converted from `.ipynb` to Markdown and included directly:
```markdown
# File: notebook.ipynb
# Converted content from Jupyter Notebook...
# End of file: notebook.ipynb
```
#### 📄 Example for PDF (`document.pdf`)
Text is extracted in Markdown format:
```markdown
# File: document.pdf
# Extracted content from PDF...
# End of file: document.pdf
```
---
## 🔧 Global Exclusion Patterns
You can create a `.mdignore` file in the same directory as the script to specify patterns that should be excluded for all repositories. The format is identical to `.gitignore`.
#### 📝 Example `.mdignore`
```plaintext
__pycache__/
*.pyc
.mypy_cache/
.env
*.log
```
---
## 👨💻 Development
To set up the development environment:
1. Create a virtual environment:
```bash
micromamba create -p ./.micromamba/ -f environment.yml
micromamba activate -p ./.micromamba/
```
2. Install the project in development mode:
```bash
pip install -e .
```
---
## 📄 License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
---
## 🤝 Contributing
1. Fork the repository.
2. Create a feature branch (`git checkout -b feature/amazing-feature`).
3. Commit your changes (`git commit -m 'Add some amazing feature'`).
4. Push to the branch (`git push origin feature/amazing-feature`).
5. Create a Pull Request.
---
## 👥 Authors
Michael (<x30827pos@gmail.com>)
---
## 🙏 Acknowledgments
Thanks to the developers of [repomix](https://github.com/yamadashy/repomix) and [git2txt](https://github.com/mrauter1/git2txt).
The idea emerged from the need for universal and simplified repository documentation
for LLM-based workflows.
Raw data
{
"_id": null,
"home_page": "https://github.com/xpos587/git2md",
"name": "git2md",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Michael",
"author_email": "x30827pos@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5c/aa/f0fd0fdfb48b8543ae60f612defc13ab85e9cdadd23dc9851b892d9b2193/git2md-1.1.7.tar.gz",
"platform": null,
"description": "# \ud83d\udd04 git2md\n\n\n\n\n\n\n\n\ud83d\ude80 A powerful command-line tool for converting Git repository contents into Markdown format.\nThis tool is perfect for developers and documentation specialists who need to create\nstructured Markdown files based on repository contents, including directory trees and file contents.\n\nRead README in Russian [here](https://github.com/Xpos587/git2md/blob/main/README_RU.md)\n\n---\n\n## \u2728 Features\n\n- **\ud83c\udf33 Repository Directory Tree Generation**: outputs repository structure in `tree` block format.\n- **\ud83d\udcdd File to Markdown Conversion**:\n - Supports syntax highlighting for code files.\n - ~~Converts Jupyter Notebook (`.ipynb`) and PDF (`.pdf`) to Markdown.~~\n- **\ud83c\udfaf Support for `.gitignore`, `.globalignore` and `.mdignore` for local projects**:\n - Automatically excludes files/directories specified in `.gitignore`, `.globalignore` or `.mdignore`.\n- **\ud83d\udd0d Custom Exclusion Patterns**: use regular expressions to exclude specific files or directories.\n- **\ud83d\uddd1\ufe0f Skip Empty Files**: ignores files without content.\n- **\ud83d\udccb Copy Results to Clipboard**: simplifies using generated Markdown.\n\n---\n\n## \ud83c\udfac Demonstration\n\nBelow is a demonstration of how `git2md` works:\n\n\n\n---\n\n## \ud83d\udccb Requirements\n\n- **\ud83d\udc0d Python 3.9 or newer**\n- **\ud83d\udc27 ~~Linux Operating System~~ Now supports Windows, MacOS, Linux (X11 and Wayland)**\n- **\ud83d\udce6 Dependencies**:\n - `pathspec` (for `.gitignore`, `.mdignore`, `.globalignore` support)\n - ~~`nbconvert` (for Jupyter Notebook conversion)~~ (support temporarily limited)\n - ~~`PyMuPDF4LLM` (for PDF conversion)~~ (support discontinued, will be replaced with better alternatives)\n - `wl-copy/xsel/xclip` (optional, Linux-only for clipboard functionality)\n\n---\n\n## \ud83d\udce5 Installation\n\n### \ud83d\udce6 Install via PyPI\n\nYou can install `git2md` directly through PyPI using pip:\n\n```bash\npip install git2md\n```\n\n### \ud83c\udfd7\ufe0f Install via AUR (Arch Linux)\n\nFor Arch Linux users, the package is available in AUR as [python-git2md](https://aur.archlinux.org/packages/python-git2md). It can be installed using AUR helpers like `paru` or `yay`:\n\n```bash\nparu -S python-git2md\n```\n\n### \ud83d\udd28 Install from Source\n\n1. Clone the repository:\n\n ```bash\n git clone https://github.com/xpos587/git2md.git\n cd git2md\n ```\n\n2. Build and install:\n\n ```bash\n python setup.py build\n pip install .\n ```\n\n---\n\n## \ud83d\ude80 Usage\n\n### \ud83d\udcbb Basic Command\n\n```bash\ngit2md [path] [options]\n```\n\nIf path is not specified, the current directory will be used.\n\n### \u2699\ufe0f Options\n\n| Option | Description |\n| ---------------- | --------------------------------------------------------------- |\n| `path` | Path to project directory or Git file (default: current folder) |\n| `-o`, `--output` | Path to save generated Markdown |\n| `-c`, `--copy` | Copy result to clipboard |\n| `--ignore` | List of patterns to exclude files or directories |\n\n---\n\n## \ud83d\udcdd Examples\n\n### \ud83d\udcc2 Generate Markdown for Entire Repository\n\n```bash\ngit2md /path/to/repo -o output.md\n```\n\n### \ud83d\udd0d Exclude Specific Files Using Patterns\n\n```bash\ngit2md --ignore \"./assets/style-*.css\" \"*.log\" \"*.tmp\" -o output.md\n```\n\n### \ud83d\uddd1\ufe0f Copy Result to Clipboard\n\n```bash\ngit2md --copy\n```\n\n---\n\n## \ud83d\udcc4 Output Format\n\n### \ud83c\udf33 Directory Tree\n\nThe directory tree is included as a code block with language identifier `tree`. For example:\n\n```tree\nsrc/\n\u251c\u2500\u2500 main.py\n\u251c\u2500\u2500 utils/\n\u2502 \u251c\u2500\u2500 helper.py\n\u2502 \u2514\u2500\u2500 __init__.py\n\u2514\u2500\u2500 README.md\n```\n\n### \ud83d\udcd1 File Contents\n\nEach file is included with its relative path in the header, followed by its contents in a code block.\n\n#### \ud83d\udc0d Example for Python File (`main.py`)\n\n````markdown\n# File: src/main.py\n\n```\nprint(\"Hello, world!\")\n```\n\n# End of file: src/main.py\n````\n\n#### \ud83d\udcd3 Example for Jupyter Notebook (`notebook.ipynb`)\n\nContent is converted from `.ipynb` to Markdown and included directly:\n\n```markdown\n# File: notebook.ipynb\n\n# Converted content from Jupyter Notebook...\n\n# End of file: notebook.ipynb\n```\n\n#### \ud83d\udcc4 Example for PDF (`document.pdf`)\n\nText is extracted in Markdown format:\n\n```markdown\n# File: document.pdf\n\n# Extracted content from PDF...\n\n# End of file: document.pdf\n```\n\n---\n\n## \ud83d\udd27 Global Exclusion Patterns\n\nYou can create a `.mdignore` file in the same directory as the script to specify patterns that should be excluded for all repositories. The format is identical to `.gitignore`.\n\n#### \ud83d\udcdd Example `.mdignore`\n\n```plaintext\n__pycache__/\n*.pyc\n.mypy_cache/\n.env\n*.log\n```\n\n---\n\n## \ud83d\udc68\u200d\ud83d\udcbb Development\n\nTo set up the development environment:\n\n1. Create a virtual environment:\n\n ```bash\n micromamba create -p ./.micromamba/ -f environment.yml\n micromamba activate -p ./.micromamba/\n ```\n\n2. Install the project in development mode:\n\n ```bash\n pip install -e .\n ```\n\n---\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository.\n2. Create a feature branch (`git checkout -b feature/amazing-feature`).\n3. Commit your changes (`git commit -m 'Add some amazing feature'`).\n4. Push to the branch (`git push origin feature/amazing-feature`).\n5. Create a Pull Request.\n\n---\n\n## \ud83d\udc65 Authors\n\nMichael (<x30827pos@gmail.com>)\n\n---\n\n## \ud83d\ude4f Acknowledgments\n\nThanks to the developers of [repomix](https://github.com/yamadashy/repomix) and [git2txt](https://github.com/mrauter1/git2txt).\n\nThe idea emerged from the need for universal and simplified repository documentation\nfor LLM-based workflows.\n",
"bugtrack_url": null,
"license": null,
"summary": "Convert Git repository contents to Markdown format",
"version": "1.1.7",
"project_urls": {
"Homepage": "https://github.com/xpos587/git2md"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "05f8a8fcbb1b06cc5bb6ef5fe53e9b882e0e7598ef932235e6f15f46ff1bb001",
"md5": "46ac2e021ad785a15e1635d6cf9d388c",
"sha256": "f99d9d6216824d408a8b3a2f0263ee7f0be501a7954c6e27e8eb3e4fed47a8af"
},
"downloads": -1,
"filename": "git2md-1.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "46ac2e021ad785a15e1635d6cf9d388c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 13587,
"upload_time": "2025-02-12T17:48:49",
"upload_time_iso_8601": "2025-02-12T17:48:49.044176Z",
"url": "https://files.pythonhosted.org/packages/05/f8/a8fcbb1b06cc5bb6ef5fe53e9b882e0e7598ef932235e6f15f46ff1bb001/git2md-1.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5caaf0fd0fdfb48b8543ae60f612defc13ab85e9cdadd23dc9851b892d9b2193",
"md5": "44c3d1ecea23383055dcbfe2acc89f0f",
"sha256": "907df69c446e0e747d6530fd8ec1d882835c2d56daf1eeffbb2032fb7b3d2d9d"
},
"downloads": -1,
"filename": "git2md-1.1.7.tar.gz",
"has_sig": false,
"md5_digest": "44c3d1ecea23383055dcbfe2acc89f0f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 13352,
"upload_time": "2025-02-12T17:48:50",
"upload_time_iso_8601": "2025-02-12T17:48:50.535544Z",
"url": "https://files.pythonhosted.org/packages/5c/aa/f0fd0fdfb48b8543ae60f612defc13ab85e9cdadd23dc9851b892d9b2193/git2md-1.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-12 17:48:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xpos587",
"github_project": "git2md",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "git2md"
}
