| Name | gittsinit JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | A powerful Python script that automatically creates Git commits with timestamps based on file creation or modification dates |
| upload_time | 2025-10-09 20:53:07 |
| maintainer | bxff |
| docs_url | None |
| author | bxff |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 Dex Devlon
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
git
commit
timestamp
version-control
automation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# gittsinit
A powerful Python CLI tool that automatically creates Git commits with timestamps based on file creation or modification dates. Perfect for backdating commits to match the actual timeline of your project's development.
## Features
### AI-Powered Commit Messages
- **Smart Message Generation**: Automatically generates descriptive commit messages using OpenAI-compatible APIs
- **Conventional Commit Format**: Follows best practices with formats like `feat:`, `fix:`, `docs:`, etc.
- **Intelligent Analysis**: Analyzes git diffs to understand the context of changes
- **Graceful Fallback**: Automatically falls back to simple date-based messages if AI generation fails
### Intelligent Timestamp Handling
- **File-Aware Timestamps**: Uses creation time for new files and modification time for existing files
- **Cross-Platform Support**: Works seamlessly on Windows, macOS, and Linux
- **Historical Accuracy**: Preserves the actual timeline of your project's development
- **Git Integration**: Properly sets both `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE`
### Flexible Targeting
- **Single File Mode**: Commit individual files with their specific timestamps
- **Directory Mode**: Recursively process entire directories, committing files in chronological order
- **Smart Filtering**: Automatically respects `.gitignore` rules and skips the `.git` directory
### Rich Configuration
- **Environment-Based Setup**: Configure all settings via `.env` file
- **Multiple AI Providers**: Compatible with OpenAI and other OpenAI-compatible APIs
- **Customizable Limits**: Adjust diff character limits for AI processing
- **Author Configuration**: Set custom Git author name and email
## Quick Start
### 1. Installation
#### Install from PyPI (Recommended)
```bash
pip install gittsinit
```
#### Install from Source
```bash
git clone https://github.com/bxff/git-commit-on-filestamp.git
cd git-commit-on-filestamp
pip install -e .
```
Ensure you have Python 3.6+ and Git installed:
```bash
python --version
git --version
```
### 2. Configuration
Copy the example environment file and configure your settings:
```bash
# If installed from source
cp .env.example .env
```
Create a `.env` file in your project directory with your configuration:
```env
# OpenAI-compatible API configuration
API_ENDPOINT=https://api.openai.com/v1/chat/completions
API_KEY=your-api-key-here
MODEL=gpt-3.5-turbo
# Git author configuration
GIT_AUTHOR_NAME=Your Name
GIT_AUTHOR_EMAIL=your.email@example.com
# Diff character limit for AI commit message generation
DIFF_CHAR_LIMIT=1000
```
### 3. Basic Usage
#### Commit Files in the Current Directory
If no path is provided, the tool defaults to the current directory.
```bash
gittsinit
```
#### Commit a Single File
```bash
gittsinit path/to/your/file.py
```
#### Commit an Entire Directory
```bash
gittsinit path/to/your/directory
```
#### Use Custom Author Information
```bash
gittsinit path/to/file.py --author "John Doe" --email "john@example.com"
```
#### Disable AI and Use Simple Messages
```bash
gittsinit path/to/file.py --no-ai
```
## Detailed Usage
### Command Line Options
| Option | Description | Default |
|--------|-------------|---------|
| `path` | Path to file or directory to commit. If not provided, defaults to the current directory. | Current working directory |
| `--author` | Git author name | From `.env` |
| `--email` | Git author email | From `.env` |
| `--no-ai` | Disable AI message generation | AI enabled |
### Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `API_ENDPOINT` | OpenAI-compatible API endpoint | Yes¹ | - |
| `API_KEY` | Your API key | Yes¹ | - |
| `MODEL` | AI model to use | Yes¹ | - |
| `GIT_AUTHOR_NAME` | Default Git author name | Yes² | - |
| `GIT_AUTHOR_EMAIL` | Default Git author email | Yes² | - |
| `DIFF_CHAR_LIMIT` | Max characters for AI diff analysis | No | `1000` |
¹ Required only when using AI-generated commit messages
² Required for all operations
### How It Works
1. **File Analysis**: The script examines each file to determine if it's new (untracked) or modified
2. **Timestamp Extraction**:
- For new files: Uses the file creation time
- For modified files: Uses the last modification time
3. **Git Status Check**: Respects `.gitignore` rules and skips ignored files
4. **Commit Message Generation**:
- **AI Mode**: Analyzes git diff and generates contextual commit messages
- **Fallback Mode**: Uses simple date-based messages
5. **Chronological Committing**: Files are committed in order of their timestamps
### Platform-Specific Behavior
#### Windows
- Uses `st_ctime` for file creation time
- Full compatibility with Git for Windows
#### macOS & Linux
- Prefers `st_birthtime` for creation time (when available)
- Falls back to `st_ctime` (inode change time) if needed
- Full compatibility with system Git installation
## Advanced Configuration
### Using Different AI Providers
The script supports any OpenAI-compatible API. Here are some examples:
#### OpenAI
```env
API_ENDPOINT=https://api.openai.com/v1/chat/completions
API_KEY=sk-your-openai-key
MODEL=gpt-3.5-turbo
```
#### Anthropic Claude (via OpenRouter)
```env
API_ENDPOINT=https://openrouter.ai/api/v1/chat/completions
API_KEY=sk-your-openrouter-key
MODEL=anthropic/claude-3.5-sonnet
```
#### Local LLM (Ollama)
```env
API_ENDPOINT=http://localhost:11434/v1/chat/completions
API_KEY=ollama
MODEL=llama3.2
```
### Performance Tuning
Adjust `DIFF_CHAR_LIMIT` based on your needs:
- **Lower values** (500-1000): Faster processing, less context
- **Higher values** (2000-5000): Better context, slower processing
- **Very high values** (10000+): Maximum context, may hit API limits
## Development
For development, clone the repository and install in editable mode:
```bash
git clone https://github.com/bxff/git-commit-on-filestamp.git
cd git-commit-on-filestamp
pip install -e .
```
This will install the package in development mode, allowing you to test changes immediately.
Raw data
{
"_id": null,
"home_page": null,
"name": "gittsinit",
"maintainer": "bxff",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "git, commit, timestamp, version-control, automation",
"author": "bxff",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d5/33/8102fdd61acba920e293b5c3be5337944c5ae8ad4096ee08bf98796d15d1/gittsinit-1.0.0.tar.gz",
"platform": null,
"description": "# gittsinit\n\n\n\n\n\n\nA powerful Python CLI tool that automatically creates Git commits with timestamps based on file creation or modification dates. Perfect for backdating commits to match the actual timeline of your project's development.\n\n## Features\n\n### AI-Powered Commit Messages\n- **Smart Message Generation**: Automatically generates descriptive commit messages using OpenAI-compatible APIs\n- **Conventional Commit Format**: Follows best practices with formats like `feat:`, `fix:`, `docs:`, etc.\n- **Intelligent Analysis**: Analyzes git diffs to understand the context of changes\n- **Graceful Fallback**: Automatically falls back to simple date-based messages if AI generation fails\n\n### Intelligent Timestamp Handling\n- **File-Aware Timestamps**: Uses creation time for new files and modification time for existing files\n- **Cross-Platform Support**: Works seamlessly on Windows, macOS, and Linux\n- **Historical Accuracy**: Preserves the actual timeline of your project's development\n- **Git Integration**: Properly sets both `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE`\n\n### Flexible Targeting\n- **Single File Mode**: Commit individual files with their specific timestamps\n- **Directory Mode**: Recursively process entire directories, committing files in chronological order\n- **Smart Filtering**: Automatically respects `.gitignore` rules and skips the `.git` directory\n\n### Rich Configuration\n- **Environment-Based Setup**: Configure all settings via `.env` file\n- **Multiple AI Providers**: Compatible with OpenAI and other OpenAI-compatible APIs\n- **Customizable Limits**: Adjust diff character limits for AI processing\n- **Author Configuration**: Set custom Git author name and email\n\n## Quick Start\n\n### 1. Installation\n\n#### Install from PyPI (Recommended)\n```bash\npip install gittsinit\n```\n\n#### Install from Source\n```bash\ngit clone https://github.com/bxff/git-commit-on-filestamp.git\ncd git-commit-on-filestamp\npip install -e .\n```\n\nEnsure you have Python 3.6+ and Git installed:\n```bash\npython --version\ngit --version\n```\n\n### 2. Configuration\n\nCopy the example environment file and configure your settings:\n```bash\n# If installed from source\ncp .env.example .env\n```\n\nCreate a `.env` file in your project directory with your configuration:\n```env\n# OpenAI-compatible API configuration\nAPI_ENDPOINT=https://api.openai.com/v1/chat/completions\nAPI_KEY=your-api-key-here\nMODEL=gpt-3.5-turbo\n\n# Git author configuration\nGIT_AUTHOR_NAME=Your Name\nGIT_AUTHOR_EMAIL=your.email@example.com\n\n# Diff character limit for AI commit message generation\nDIFF_CHAR_LIMIT=1000\n```\n\n### 3. Basic Usage\n\n#### Commit Files in the Current Directory\nIf no path is provided, the tool defaults to the current directory.\n```bash\ngittsinit\n```\n\n#### Commit a Single File\n```bash\ngittsinit path/to/your/file.py\n```\n\n#### Commit an Entire Directory\n```bash\ngittsinit path/to/your/directory\n```\n\n#### Use Custom Author Information\n```bash\ngittsinit path/to/file.py --author \"John Doe\" --email \"john@example.com\"\n```\n\n#### Disable AI and Use Simple Messages\n```bash\ngittsinit path/to/file.py --no-ai\n```\n\n## Detailed Usage\n\n### Command Line Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `path` | Path to file or directory to commit. If not provided, defaults to the current directory. | Current working directory |\n| `--author` | Git author name | From `.env` |\n| `--email` | Git author email | From `.env` |\n| `--no-ai` | Disable AI message generation | AI enabled |\n\n### Environment Variables\n\n| Variable | Description | Required | Default |\n|----------|-------------|----------|---------|\n| `API_ENDPOINT` | OpenAI-compatible API endpoint | Yes\u00b9 | - |\n| `API_KEY` | Your API key | Yes\u00b9 | - |\n| `MODEL` | AI model to use | Yes\u00b9 | - |\n| `GIT_AUTHOR_NAME` | Default Git author name | Yes\u00b2 | - |\n| `GIT_AUTHOR_EMAIL` | Default Git author email | Yes\u00b2 | - |\n| `DIFF_CHAR_LIMIT` | Max characters for AI diff analysis | No | `1000` |\n\n\u00b9 Required only when using AI-generated commit messages \n\u00b2 Required for all operations\n\n### How It Works\n\n1. **File Analysis**: The script examines each file to determine if it's new (untracked) or modified\n2. **Timestamp Extraction**: \n - For new files: Uses the file creation time\n - For modified files: Uses the last modification time\n3. **Git Status Check**: Respects `.gitignore` rules and skips ignored files\n4. **Commit Message Generation**:\n - **AI Mode**: Analyzes git diff and generates contextual commit messages\n - **Fallback Mode**: Uses simple date-based messages\n5. **Chronological Committing**: Files are committed in order of their timestamps\n\n### Platform-Specific Behavior\n\n#### Windows\n- Uses `st_ctime` for file creation time\n- Full compatibility with Git for Windows\n\n#### macOS & Linux\n- Prefers `st_birthtime` for creation time (when available)\n- Falls back to `st_ctime` (inode change time) if needed\n- Full compatibility with system Git installation\n\n## Advanced Configuration\n\n### Using Different AI Providers\n\nThe script supports any OpenAI-compatible API. Here are some examples:\n\n#### OpenAI\n```env\nAPI_ENDPOINT=https://api.openai.com/v1/chat/completions\nAPI_KEY=sk-your-openai-key\nMODEL=gpt-3.5-turbo\n```\n\n#### Anthropic Claude (via OpenRouter)\n```env\nAPI_ENDPOINT=https://openrouter.ai/api/v1/chat/completions\nAPI_KEY=sk-your-openrouter-key\nMODEL=anthropic/claude-3.5-sonnet\n```\n\n#### Local LLM (Ollama)\n```env\nAPI_ENDPOINT=http://localhost:11434/v1/chat/completions\nAPI_KEY=ollama\nMODEL=llama3.2\n```\n\n### Performance Tuning\n\nAdjust `DIFF_CHAR_LIMIT` based on your needs:\n- **Lower values** (500-1000): Faster processing, less context\n- **Higher values** (2000-5000): Better context, slower processing\n- **Very high values** (10000+): Maximum context, may hit API limits\n\n## Development\n\nFor development, clone the repository and install in editable mode:\n\n```bash\ngit clone https://github.com/bxff/git-commit-on-filestamp.git\ncd git-commit-on-filestamp\npip install -e .\n```\n\nThis will install the package in development mode, allowing you to test changes immediately.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Dex Devlon\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "A powerful Python script that automatically creates Git commits with timestamps based on file creation or modification dates",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/bxff/git-commit-on-filestamp/issues",
"Documentation": "https://github.com/bxff/git-commit-on-filestamp#readme",
"Homepage": "https://github.com/bxff/git-commit-on-filestamp",
"Repository": "https://github.com/bxff/git-commit-on-filestamp.git"
},
"split_keywords": [
"git",
" commit",
" timestamp",
" version-control",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8b67c69c665b287abf27de698c77e39984cf937be50410e2bcffb5e0bd48933e",
"md5": "1eac68d04bf95e1875654df3ad06c9a7",
"sha256": "a30fb18520f237e5ea726c8bb7fe86d2ec4e24ab3b04cf9abf2360e58d63a9ca"
},
"downloads": -1,
"filename": "gittsinit-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1eac68d04bf95e1875654df3ad06c9a7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19807,
"upload_time": "2025-10-09T20:53:06",
"upload_time_iso_8601": "2025-10-09T20:53:06.094387Z",
"url": "https://files.pythonhosted.org/packages/8b/67/c69c665b287abf27de698c77e39984cf937be50410e2bcffb5e0bd48933e/gittsinit-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d5338102fdd61acba920e293b5c3be5337944c5ae8ad4096ee08bf98796d15d1",
"md5": "8f20c833b78a6147db93ff734c58297f",
"sha256": "f5d18c0ef1bbe3c2a32f89eebbedb6462eaa762f721614a478d51a8b92c826f8"
},
"downloads": -1,
"filename": "gittsinit-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8f20c833b78a6147db93ff734c58297f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22164,
"upload_time": "2025-10-09T20:53:07",
"upload_time_iso_8601": "2025-10-09T20:53:07.468839Z",
"url": "https://files.pythonhosted.org/packages/d5/33/8102fdd61acba920e293b5c3be5337944c5ae8ad4096ee08bf98796d15d1/gittsinit-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-09 20:53:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bxff",
"github_project": "git-commit-on-filestamp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gittsinit"
}
