README

A Laravel package that keeps your project in sync with the template repository it was created from. Run one command to pull in the latest changes from your template — conflicts are caught, local overrides are preserved, and a backup branch is created before every sync.

Installation

composer require drlopes/template-sync

Publish the config file:

php artisan vendor:publish --tag="template-sync-config"

Usage

1. Connect to your template

Run the interactive setup command once. It prompts for your template repository URL and preferences, writes config/template-sync.php, and adds the git remote:

php artisan template:connect

You will be asked for:

Template repository URL — the GitHub/GitLab URL of the template repo
Remote name — the git remote name to use (default: template)
Branch — which branch on the template to merge from (default: main)
Allow unrelated histories — pass --allow-unrelated-histories to git merge; needed when the repo was created from a GitHub template
Auto-delete backup branch — whether to remove the backup branch after a successful sync
Excluded paths — files to keep at your local version even when the template changes them

2. Sync template changes

Pull in the latest changes from the template at any time:

php artisan template:update

The command will:

Add the template remote if it is missing
Create a backup branch (e.g. backup/before-template-update-2025-05-16) so you have a restore point
Fetch and merge the template branch
If the merge conflicts, pause with the merge in progress so you can resolve the conflicts yourself (see below)
If the merge succeeds, restore any excluded paths to their local versions, then commit

Resolving conflicts

When the merge runs into conflicts, the command stops and leaves the repository in a mid-merge state — your working tree contains the conflict markers, just like a normal git merge. You then have two options:

Finish the sync — fix the conflicts in your editor, stage the resolved files, and continue:

# edit the conflicted files...
git add <resolved files>
php artisan template:update --continue

--continue re-applies your excluded paths, creates the sync commit, and cleans up the backup branch if delete_on_success is enabled.

Abort the sync — discard the merge and return to where you were:

php artisan template:update --abort

--abort runs git merge --abort and leaves the backup branch in place so you can still inspect it.

While a sync is paused, re-running php artisan template:update without a flag will refuse to start a new sync and remind you to use --continue or --abort.

Configuration

// config/template-sync.php

return [

    /*
     * The name of the git remote pointing to the template repository.
     */
    'remote_name' => 'template',

    /*
     * The URL of the template repository.
     * Set this manually or run: php artisan template:connect
     */
    'url' => null,

    /*
     * The branch on the template repository to merge from.
     */
    'branch' => 'main',

    /*
     * Merge strategy. Currently only 'merge' is supported.
     */
    'merge_strategy' => 'merge',

    /*
     * Whether to pass --allow-unrelated-histories to git merge.
     * Enable this if git refuses to merge due to unrelated histories
     * (common when the repo was created from a GitHub template).
     */
    'allow_unrelated_histories' => false,

    /*
     * Backup branch settings. A backup branch is created before every
     * sync so you have a restore point if anything goes wrong.
     */
    'backup_branch' => [
        'enabled' => true,
        'prefix' => 'backup/before-template-update',
        'delete_on_success' => true,
    ],

    /*
     * Paths to keep at their local version even when the template changes them.
     * After merging, these files are restored to HEAD before committing.
     */
    'excluded_paths' => [
        // 'README.md',
        // '.env.example',
    ],

];

Excluded paths

Use excluded_paths for files your project has customised and should never receive template updates. After every successful merge, those files are restored to your local version before the commit is made, so template changes to them are silently dropped.

Backup branch

Before every sync, a branch named {prefix}-{date} (e.g. backup/before-template-update-2025-05-16) is created at your current HEAD as a safety net. It is preserved whenever the sync pauses on conflicts or is aborted, so you can always git checkout it to get back to your previous state. Set delete_on_success to false to keep it even after a clean sync.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

drlopes / template-sync

Maintainers

Package info

Fund package maintenance!

Statistics

Security