Setting up Laravel project with Git

Setting up Laravel project with Git

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Managing Laravel Projects: Local Forking and Upstream Merges

A common point of confusion for developers working with open-source frameworks like Laravel is how to maintain a local development environment while staying synchronized with upstream changes. The standard approach involves establishing a "fork" relationship rather than simply cloning the official repository directly into your project folder. If you clone https://github.com/laravel/laravel.git directly, you own that repository; any changes you make locally will be overwritten if you pull updates later, and you cannot push your modifications back upstream without administrative access to the original repo.

The correct workflow is to create a fork of the official Laravel repository on GitHub under your own account. Once this remote repository exists, you clone it to your local machine. This establishes two critical remote connections: one pointing to your personal fork (the default origin) and another pointing to the upstream official repository (https://github.com/laravel/laravel.git).

Here is the step-by-step implementation using Git commands. First, fork the Laravel repository on GitHub and navigate to your local project directory. Clone your own fork as the primary remote:

git clone https://github.com/YOUR_USERNAME/laravel.git my-laravel-project
cd my-laravel-project
git remote add origin https://github.com/YOUR_USERNAME/laravel.git

Next, you must add the upstream remote so Git knows where to fetch official updates from. Run the following command:

git remote add upstream https://github.com/laravel/laravel.git

You can verify these connections with git remote -v, which should list both origin pointing to your fork and upstream pointing to the official Laravel repo.

Synchronizing Your Codebase

The core challenge is merging changes from the upstream repository without losing your local commits or introducing merge conflicts that break your application. The safest strategy is to keep your development work on a feature branch rather than the default main or master branch. This isolates your customizations and provides a clear target for merges.

When you need to update your project with the latest upstream changes, do not push directly to the main branch. Instead, fetch the new commits from the upstream remote:

git fetch upstream

This downloads the new history but keeps it separate until you are ready to integrate it. To merge these changes into your current working branch, use git merge:

git merge upstream/main
# or git merge upstream/master if that is the default upstream branch name

This operation will attempt to replay the upstream commits onto your local history. If the code has diverged significantly, Git may report a merge conflict. These are not errors but rather opportunities to resolve discrepancies where both you and the upstream maintainers modified the same lines. You must edit the conflicted files manually to choose between your changes or the upstream ones, then stage the resolution with git add before committing.

Handling Conflicts and Best Practices

A frequent pitfall is attempting to merge directly into the main branch of your fork. While this works for simple updates, it often leads to a history that is difficult to read and debug. Maintaining a feature branch (e.g., feature/my-customization) allows you to cherry-pick specific upstream fixes or merge entire release branches only when necessary.

If a direct merge fails due to conflicts, consider using git rebase instead. Replaying your local commits on top of the updated upstream history can result in a cleaner linear project history. However, rebasing is more complex to resolve if conflicts occur, so it requires careful handling.

For most daily development tasks, sticking to the merge workflow on a dedicated feature branch is the most robust approach. It ensures that your local environment remains stable while allowing you to selectively adopt upstream improvements. This separation of concerns—keeping your custom logic isolated from framework updates—is essential for long-term maintainability.

If you encounter issues with dependency versions or artisan commands after merging, always check composer.lock and run composer update to ensure your vendor dependencies align with the new Laravel version. Finally, remember that pushing changes back to your upstream fork should only happen once your local branch is resolved and tested, ensuring your unique contributions are preserved correctly on GitHub.

Our network