Download the PHP package aaronidikko/laravel-git-sync without Composer

Laravel Git Sync

A Laravel package that enables developers to commit and push code changes to Git with a single command.

Quick Start

Global Installation (Recommended for Personal Use):

Note: If you get "command not found: git-sync", see the PATH setup instructions below.

Per-Project Installation (Recommended for Teams):

Optional: Run php artisan git:sync:install to enable the shorter composer sync command. Details below.

Features

• Dual Installation Modes: Install globally or per-project
• Single command to stage, commit, and push changes
• Custom or auto-generated timestamped commit messages
• Multiple workflows: commit-only, push-only, pull-before-push, dry-run modes
• Comprehensive error handling for common Git scenarios
• Configurable commit message prefixes and timestamp formats
• Automatic branch detection and upstream setup
• Pull integration: Optionally pull remote changes before pushing
• Verbose mode for detailed output
• Works in non-Laravel projects (when installed globally)

Installation

You can install this package in two ways:

Option 1: Per-Project Installation (Recommended for Teams)

Install in a specific Laravel project:

Benefits:

• Team members get the package automatically via composer install
• Configuration can be version-controlled
• Consistent across the team

Optional: Enable composer sync (One-Time Setup)

The php artisan git:sync command is automatically available after installation. The install command below is optional and only adds a convenient composer sync shortcut.

Run this command once to add a composer sync shortcut to your project:

What it does:

• Adds "sync": "@php artisan git:sync" to your project's composer.json
• Creates a shortcut: composer sync → calls → php artisan git:sync
• Does not affect the php artisan git:sync command (always works)

After running install, you can use:

Available Commands:

Option 2: Global Installation (Recommended for Personal Use)

Install once, use everywhere:

Important: Add Composer's bin directory to your PATH

After installation, you need to add Composer's global bin directory to your PATH to use the git-sync command:

Step 1: Find your Composer bin directory

This is usually ~/.composer/vendor/bin or ~/.config/composer/vendor/bin

Step 2: Add to PATH based on your shell

For Bash (add to ~/.bashrc or ~/.bash_profile):

For Zsh (add to ~/.zshrc):

For Fish (add to ~/.config/fish/config.fish):

Step 3: Verify installation

Benefits:

• Install once, use in all Laravel projects
• Works even in non-Laravel git repositories
• Quick access via git-sync command

Usage:

Publishing Configuration (Per-Project Only)

If you installed per-project and want to customize settings:

This creates config/git-sync.php where you can customize commit message format, prefixes, etc.

Installation Comparison

Usage

The package provides different commands based on installation type:

1. Global Command (If Installed Globally)

Simplest and fastest option:

2. Artisan Command (Per-Project Installation)

Standard Laravel command:

3. Direct Binary (Per-Project Installation)

Alternative for per-project installations:

Optional: Add Composer Script Shortcut

Note: The php artisan git:sync command works immediately after installation. This section is optional and only adds a shorter composer sync alias.

To enable composer sync in your project, run this one-time setup command:

This automatically adds "sync": "@php artisan git:sync" to your project's composer.json, creating a shortcut.

Then use:

How It Works

All commands will:

1. Stage all changes (git add .)
2. Commit with message like chore: 2025-10-25 09:30 (or your custom message)
3. Push to the current branch

Which Command Should I Use?

Understanding the Commands

Q: What's the difference between php artisan git:sync and composer sync?

A: They do the exact same thing! composer sync is just a shortcut that internally calls php artisan git:sync.

• php artisan git:sync - Available immediately after composer require
• composer sync - Only available after running php artisan git:sync:install (one-time setup)

Q: Do I need to run git:sync:install?

A: No, it's completely optional! Use it only if you prefer typing composer sync instead of php artisan git:sync.

Q: What does git:sync:install do?

A: It adds this line to your project's composer.json:

This creates a Composer script alias, nothing more.

Command Options Reference

All commands support the same options:

Examples with git-sync (Global):

Examples with artisan (Per-Project):

Examples with vendor/bin (Per-Project):

Configuration

After publishing the config file, you can customize settings in config/git-sync.php:

Environment Variables

You can also configure via .env:

Examples

Daily Development Workflow

With Global Installation:

With Per-Project Installation:

Working with Feature Branches

Global:

Per-Project:

Using in Non-Laravel Projects

If you have the package installed globally, it works even in non-Laravel git repositories with basic git sync functionality:

Note: Configuration options (custom prefixes, timestamp format, etc.) only work in Laravel projects with the config file published.

Handling Remote Changes

When the remote repository has commits that you don't have locally, you need to pull those changes before pushing. The --pull option handles this automatically:

Global:

Per-Project:

The pull respects your git configuration. If you have pull.rebase=true set, it will rebase your commits. Otherwise, it will merge.

Note: If there are merge conflicts during the pull, the command will stop and prompt you to resolve them manually.

Error Handling

The package handles common Git scenarios:

• Not a Git repository: Prompts to initialize Git
• No remote configured: Shows how to add a remote
• No upstream branch: Automatically sets upstream
• Remote has changes: Suggests pulling first (or use --pull option)
• Merge conflicts: Stops and prompts to resolve manually
• No changes to commit: Informs you the working tree is clean

Troubleshooting

"command not found: git-sync" (Global Installation)

If you get this error after global installation, Composer's bin directory is not in your PATH.

Solution:

1. Find your Composer bin directory:

2. Add it to your PATH (choose based on your shell):

   For Bash:

   For Zsh:

3. Verify it works:

"Command sync is not defined" (Per-Project Installation)

The composer sync command doesn't work automatically after installing the package. It requires a one-time setup.

Solution:

Run the install command to enable composer sync:

This automatically adds the sync script to your composer.json.

Alternative: Use these commands without setup:

Requirements

• PHP 8.2 or higher
• Laravel 10.x, 11.x, or 12.x
• Git installed on your system

Testing

Run the test suite:

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is open-sourced software licensed under the MIT license.

Credits

Created by Aaron Idikko

Support

If you find this package helpful, please consider:

• Starring the repository on GitHub
• Sharing it with others
• Reporting issues or suggesting features

Changelog

Version 1.2.0

• Added --pull option to pull remote changes before pushing
• Prevents commit history issues when remote has new commits
• Works with both rebase and merge strategies
• Handles merge conflicts gracefully
• Available in all command modes (artisan, composer, global)
• Added php artisan git:sync:install command for one-time composer sync setup
• Automatically adds composer sync script to project's composer.json
• Added comprehensive PATH setup instructions for global installation
• Added troubleshooting section for common installation issues
• Clarified usage commands for per-project vs global installation

Version 1.0.0

• Initial release
• Basic git sync functionality
• Custom and auto-generated commit messages
• Multiple workflow modes
• Comprehensive error handling
• Configuration options
• Test suite