Pulling Updates

This guide explains how to receive updates from the original next-template repository after you've cloned it for your own project.

Quick Start

Run the included script to pull and merge upstream changes:

npm run pull-upstream

This interactive script handles everything automatically—including setting up the upstream remote, fetching changes, and letting you choose which files to update.

Using the Pull Upstream Script

The scripts/pull-upstream.sh script provides an interactive experience for merging template updates.

Features

• Automatic setup – Adds the upstream remote if not already configured
• Change preview – Shows you what commits and files changed before merging
• Interactive file selection – Choose which files to merge or exclude
• Permanent ignore list – Skip files you never want updated via .upstream-ignore
• Deleted file handling – Asks before recreating files you intentionally deleted
• Conflict detection – Alerts you if merge conflicts need manual resolution

Usage

# Pull from main branch (default)
npm run pull-upstream

# Pull from a specific branch
./scripts/pull-upstream.sh develop

Interactive Controls

When prompted to select files:

The .upstream-ignore File

Files added to .upstream-ignore will always keep your local version during merges. The script creates and manages this file for you, but you can also edit it manually:

# Files to exclude from upstream template merges
# Supports glob patterns

.env
src/config/custom-settings.ts
public/logo.svg

Manual Method

If you prefer to manage updates manually without the script:

Initial Setup (One-Time)

Add the original repository as an upstream remote:

git remote add upstream https://github.com/CarrettaRiccardo/next-template.git

Verify the remote was added:

git remote -v

Pulling Updates

1. Fetch the latest changes:

   git fetch upstream

2. Merge the updates into your branch:

   git merge upstream/main

3. Resolve any conflicts:

   git add .
   git commit -m "Merge upstream template updates"

Alternative: Rebase

If you prefer a cleaner history:

git fetch upstream
git rebase upstream/main

[!WARNING] Only use rebase if you haven't pushed your changes to a shared repository, or if you're comfortable force-pushing.

Best Practices

• Commit your work first – Always commit or stash local changes before pulling updates
• Review the changelog – Check the template's release notes or commit history for breaking changes
• Test after merging – Run npm run dev and npm run type-check to ensure everything works
• Keep customizations isolated – When possible, extend rather than modify core template files to minimize conflicts

Troubleshooting

"fatal: refusing to merge unrelated histories"

If you see this error, it usually means the repositories don't share a common ancestor. You can force the merge:

git merge upstream/main --allow-unrelated-histories

Frequent Conflicts

If you consistently have conflicts in the same files:

1. Add them to .upstream-ignore to always keep your local version
2. Consider creating wrapper files instead of modifying template files directly
3. Use environment variables and configuration files for customizations