ahmedessam / laravel-git-toolkit
A toolkit for managing git repositories in Laravel applications.
Requires
- php: ^8.2
- illuminate/console: ^12.0|^11.0|^10.0|^9.0
- illuminate/support: ^12.0|^11.0|^10.0|^9.0
Requires (Dev)
- mockery/mockery: ^1.6
- orchestra/testbench: ^9.0|^8.0|^7.0
- phpunit/phpunit: ^10.0|^11.0
README
Laravel Git Toolkit is a comprehensive package that integrates Git operations within your Laravel projects. It provides commands and services to help manage Git workflows more efficiently, with support for Git Flow, conventional commits, and modern Laravel architecture patterns.
Installation
You can install the package via Composer:
composer require ahmedessam/laravel-git-toolkit
You can publish the configuration file with:
php artisan vendor:publish --tag=git-toolkit-config
Environment Variables
The package uses the following environment variables:
GIT_PUSH_TO_DEFAULT_BRANCH
- Whether to push changes to the default branch. Default isfalse
.GIT_DEFAULT_BRANCH
- The default branch to push changes to. Default iscurrent
.GIT_PUSH_WITH_DEFAULT_MESSAGE
- Whether to push changes with the default commit message. Default isfalse
.GIT_DEFAULT_COMMIT_TYPE
- The default commit type. Default isfeat
.GIT_DEFAULT_COMMIT_MESSAGE
- The default commit message. Default isUpdate [%s] branch with latest changes.
.GIT_PUSH_AFTER_COMMIT
- Whether to push changes after committing. Default istrue
.GIT_RETURN_TO_PREVIOUS_BRANCH
- Whether to return to the previous branch after committing. Default istrue
.GIT_DELETE_AFTER_MERGE
- Whether to delete the merged branch after merging. Default isfalse
.GIT_FLOW_ENABLED
- Whether to enable Git flow branches. Default istrue
.
You can add these environment variables to your .env
file.
copy the following code to your .env
file:
GIT_PUSH_TO_DEFAULT_BRANCH=false GIT_DEFAULT_BRANCH='current' GIT_PUSH_WITH_DEFAULT_MESSAGE=false GIT_DEFAULT_COMMIT_TYPE='feat' GIT_DEFAULT_COMMIT_MESSAGE='Update [%s] branch with latest changes.' GIT_PUSH_AFTER_COMMIT=true GIT_RETURN_TO_PREVIOUS_BRANCH=true GIT_DELETE_AFTER_MERGE=false GIT_FLOW_ENABLED=true
Notes
- The package uses the
git
command to perform Git operations. - The package asks few questions to get the required data to perform the operation.
- The package provides a list of flags to specify the required data to perform the operation.
- The package uses the following flags:
--branch
flag to specify the branch name.--message
flag to specify the commit message.--type
flag to specify the commit type.--merge
flag to specify the branch to merge.--return
flag to specify whether to return to the previous branch.--commit
flag to specify the commit hash to reset to.
Usage
To initialize git flow branches, run the following command:
php artisan git:flow
This command will create the following main branches:
main
develop
staging
hotfix
You can also create feature, fix, and release branches, package ask for theses branches names.
To commit changes, run the following command:
php artisan git push
This command will add all changes, commit them, and push them to the current branch.
To create a new branch, run the following command:
php artisan git branch
This command will create a new branch based on the type you choose.
To pull changes from the remote repository, run the following command:
php artisan git pull
This command will pull changes from the remote repository to the current branch or the branch you specify.
To merge branches, run the following command:
php artisan git merge --merge=<source-branch> --branch=<target-branch>
Flags
--merge
flag to specify the branch to merge from.--branch
flag to specify the branch or branches sperated by comma or space to merge into.- ex:
php artisan git merge --merge=feature --branch=develop,main
This command will merge the specified branch into the branch you specify.
To delete a branch, run the following command:
php artisan git delete-branch
This command will delete the specified branch.
To Push new branch to remote repository, run the following command:
php artisan git push-branch
To Fetch changes from the remote repository, run the following command:
php artisan git fetch
This command will fetch changes from the remote repository.
To Rebase changes from the remote repository, run the following command:
php artisan git rebase
This command will rebase changes from the remote repository.
To Reset changes from the remote repository, run the following command:
php artisan git reset --commit=<commit-hash>
This command will reset changes from the remote repository.
Features
✨ Core Git Operations
- Initialize Git flow branches with customizable naming
- Commit changes with conventional commit messages
- Create branches for features, fixes, releases, hotfixes, or custom types
- Pull, push, merge, delete, fetch, rebase, and reset operations
🏗️ Modern Architecture
- Contract-based service architecture
- Event-driven operations for extensibility
- Pipeline validation system
- Comprehensive exception handling
- Dependency injection throughout
🎯 Laravel Integration
- Laravel 9-12 compatibility
- Artisan command integration
- Service provider with automatic discovery
- Configuration management
- Event system integration
Requirements
- PHP 8.2 or higher
- Laravel 9.x, 10.x, 11.x, or 12.x
- Git installed and configured
- Remote repository access (SSH recommended)
Architecture
Contracts
The package uses contract interfaces for clean dependency injection:
// GitRepositoryInterface for Git operations app(GitRepositoryInterface::class)->getCurrentBranch(); // ConfigInterface for configuration access app(ConfigInterface::class)->get('commit_types');
Events
Listen to Git operations in your application:
Event::listen(BranchCreated::class, function ($event) { Log::info("Branch created: {$event->branchName}"); }); Event::listen(CommitPushed::class, function ($event) { Log::info("Commit pushed: {$event->commitHash}"); });
Services
Access core services directly:
// Branch operations $branchService = app(BranchService::class); $branchName = $branchService->sanitizeBranchName('feature/my-feature'); // Commit message building $commitBuilder = app(CommitMessageBuilder::class); $message = $commitBuilder->buildCommitMessage('feat', 'Add new feature'); // Git repository operations $gitRepo = app(GitRepository::class); $branches = $gitRepo->getAllBranches();
Testing
Run the test suite:
composer test
Run tests with coverage:
composer test-coverage
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details on how to contribute.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
License
The Laravel Git Toolkit is open-sourced software licensed under the MIT license.
Author
- Ahmed Essam
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Issues
If you find any issues with the package or have any questions, please feel free to open an issue on the GitHub repository.
Enjoy using Laravel Git Toolkit! 🚀