Updating Template

As the PutOut project evolves, new features, improvements, and bug fixes are regularly added to the main template. To ensure your PutOut-based website benefits from these updates, you can follow this guide to sync your project with the original template.

Prerequisites

  • Git installed on your local machine
  • Basic knowledge of Git commands
  • Your PutOut-based project set up in a local Git repository

Update Process

Follow these steps to update your PutOut instance with the latest changes from the original template:

1. Add the Original Template as a Remote

First, you need to add the PutOut template repository as a remote to your local project. You only need to do this once.

git remote add template https://github.com/deepakness/putout.git

2. Fetch the Latest Changes

Fetch the latest changes from the template repository:

git fetch template

3. Merge the Changes

Merge the changes from the template's main branch into your project's main branch:

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

The --allow-unrelated-histories flag is necessary because your project and the template have separate Git histories.

4. Resolve Conflicts

If there are any conflicts between your changes and the template updates, Git will notify you. Resolve these conflicts manually:

  1. Open the conflicting files in your code editor.
  2. Look for conflict markers (<<<<<<<, =======, >>>>>>>).
  3. Decide which changes to keep and which to discard.
  4. Remove the conflict markers.
  5. Save the files.

5. Commit the Merged Changes

After resolving any conflicts, stage and commit the changes. First stage:

git add .

And then commit:

git commit -m "Merged updates from PutOut template"

6. Push to Your Repository

Finally, push the updated branch to your remote repository:

git push origin main

Best Practices

  • Backup: Always create a backup of your project before updating.
  • Review Changes: Carefully review the changes from the template before merging.
  • Test Thoroughly: After updating, thoroughly test your website to ensure everything works as expected.
  • Update Regularly: To minimize potential conflicts, consider updating your project regularly.

Troubleshooting

If you encounter issues during the update process:

  1. Ensure you have a clean working directory (no uncommitted changes) before starting the update.
  2. If the merge becomes too complex, consider cherry-picking specific commits instead of merging the entire branch.
  3. For persistent problems, you can always start fresh by cloning the latest template and manually reapplying your customizations.

By following this guide, you can ensure that your PutOut site stays up-to-date with the latest features and improvements.