Instructions for setting up the project and keeping track of changes in the original repository. This guide covers cloning, Docker setup, and Git workflow management.
Instructions for setting up the project and keeping track of changes in the original repository. This guide covers cloning, Docker setup, and Git workflow management.
Install Required Tools:
Clone the Repository:
1git clone https://github.com/<upstream-repo-owner>/hbstack.git my-hbstack-project
2cd my-hbstack-project
Initialize Your Own Repository:
1# Remove the original git history
2rm -rf .git
3
4# Initialize a new git repository
5git init
6
7# Add all files to the new repository
8git add .
9
10# Make the initial commit
11git commit -m "Initial commit based on HBStack"
12
13# Create a new repository on GitHub/GitLab/etc. and then:
14git remote add origin https://github.com/your-username/your-repo-name.git
15git push -u origin main
Set Up Hugo Modules:
1# Initialize Hugo modules
2hugo mod init github.com/your-username/your-repo-name
3
4# Get all dependencies
5hugo mod get -u
Build the Docker Environment:
1docker compose build
Start the Development Server:
Default server:
1docker compose up server
Development server (memory):
1docker compose up dev-memory
Verify the Setup:
Open your browser and navigate to http://localhost:1313 to ensure the project is running.
Forking a project creates a direct link between your repository and the original repository. While this is useful for contributing back to the original project, it may not be ideal for the following reasons:
Independence:
Clean Git History:
Flexibility:
Add the original HBStack repository as an upstream remote to track changes:
1git remote add upstream https://github.com/<upstream-repo-owner>/hbstack.git
Verify that the upstream remote has been added:
1git remote -v
Before syncing with the upstream repository, ensure your local changes are properly managed:
Commit or Stash Local Changes:
1# Check for uncommitted changes
2git status
3
4# Commit your changes if needed
5git add .
6git commit -m "Your commit message describing local changes"
7
8# Alternatively, stash changes if you're not ready to commit
9git stash save "Work in progress"
Create a Backup Branch (Optional but Recommended):
1# Create a backup of your current state
2git branch backup-before-sync-$(date +%Y%m%d)
You should consider syncing with the upstream repository in the following situations:
Follow these steps to sync your repository with the upstream changes:
Fetch the Latest Changes:
1git fetch upstream
Choose Your Merge Strategy:
Option A: Merge Approach (Preserves History)
1# Ensure you're on your main branch
2git checkout main
3
4# Merge upstream changes
5git merge upstream/main
6
7# Resolve any conflicts if they occur
8# After resolving conflicts:
9git add .
10git commit -m "Merge upstream changes"
Option B: Rebase Approach (Cleaner History)
1# Ensure you're on your main branch
2git checkout main
3
4# Rebase on top of upstream changes
5git rebase upstream/main
6
7# Resolve any conflicts if they occur
8# After resolving conflicts:
9git add .
10git rebase --continue
Option C: Cherry-Pick Approach (Selective Updates)
1# Fetch and view upstream commits
2git fetch upstream
3git log --oneline upstream/main
4
5# Cherry-pick specific commits
6git cherry-pick <commit-hash>
Update Hugo Modules:
1# Update all Hugo modules
2hugo mod get -u
Test the Changes:
1# Start the development server
2docker compose up server
Push to Your Repository:
1git push origin main
For more systematic tracking, consider setting up a scheduled task or GitHub Action:
Create a Sync Script:
1#!/bin/bash
2# sync-upstream.sh
3
4echo "Fetching upstream changes..."
5git fetch upstream
6
7echo "Merging changes from upstream/main..."
8git merge upstream/main
9
10echo "Updating Hugo modules..."
11hugo mod get -u
12
13echo "Pushing changes to origin..."
14git push origin main
15
16echo "Sync completed!"
Make the Script Executable:
1chmod +x sync-upstream.sh
Set Up a Cron Job (Optional):
1# Edit crontab
2crontab -e
3
4# Add a monthly sync job (runs at 1 AM on the 1st of each month)
50 1 1 * * /path/to/your/repo/sync-upstream.sh >> /path/to/your/repo/sync-log.txt 2>&1
HBStack and HUGOMODS use Hugo Modules extensively. To manage these dependencies:
List Current Modules:
1hugo mod graph
Update All Modules:
1hugo mod get -u
Update a Specific Module:
1hugo mod get -u github.com/hugomods/icons/vendors/bootstrap
Clean Module Cache:
1hugo mod clean
For more information on available modules and their documentation, visit HUGOMODS.
By following these guidelines, you can maintain your own HBStack-based project while benefiting from updates and improvements in the original repository.