Syncing Across Devices

This tutorial shows you how to set up Git synchronization to keep your HeroJournal achievements in sync between your work computer, personal laptop, or any other devices.

Overview

We’ll set up a private GitHub repository that stores your achievements. Both devices will sync to this repository, keeping everything consistent.

What you’ll need:

• A GitHub account (or GitLab/Bitbucket)
• HeroJournal installed on both devices
• About 15 minutes

Part 1: Create the Repository

Step 1: Create a New Repository

1. Go to github.com/new
2. Fill in the details:
   • Repository name: herojournal-data (or any name you prefer)
   • Description: “HeroJournal achievement data” (optional)
   • Visibility: Select Private (important!)
   • Initialize: Leave all checkboxes unchecked
3. Click Create repository

Step 2: Copy the Repository URL

On the new repository page:

1. Click the green Code button
2. Select HTTPS
3. Copy the URL (looks like https://github.com/yourusername/herojournal-data.git)

Step 3: Create a Personal Access Token

1. Go to github.com/settings/tokens
2. Click Generate new token > Generate new token (classic)
3. Fill in:
   • Note: “HeroJournal sync”
   • Expiration: 90 days (or longer)
   • Scopes: Check only repo (full repository access)
4. Click Generate token
5. Copy the token immediately (you won’t see it again!)

Part 2: Set Up First Device

Step 1: Open Git Settings

1. Launch HeroJournal on your primary device
2. Go to Settings > Git tab

Step 2: Configure Repository

1. Enable Git sync with the toggle
2. Paste your repository URL
3. Enter your GitHub username
4. Paste your personal access token
5. Click Connect

Step 3: Initial Sync

1. Click Sync Now
2. Wait for the sync to complete
3. You should see “Synced successfully” or similar

Your achievements are now backed up to GitHub!

Part 3: Set Up Second Device

Step 1: Open Git Settings

1. Launch HeroJournal on your second device
2. Go to Settings > Git tab

Step 2: Configure (Same Settings)

1. Enable Git sync
2. Paste the same repository URL
3. Enter your GitHub username
4. Paste the same personal access token
5. Click Connect

Step 3: Pull Data

1. Click Pull (not Sync yet)
2. Wait for the download to complete
3. Your achievements from the first device now appear!

Part 4: Daily Usage

Recommended Workflow

When starting work:

1. Open HeroJournal
2. Git auto-syncs (if enabled) or click Sync

When adding achievements:

• Just save normally
• Auto-commit handles the rest (if enabled)

When switching devices:

1. Sync on current device before closing
2. Sync on new device after opening

Enable Auto-Sync

For seamless syncing:

1. Go to Settings > Git
2. Enable Auto-commit - commits on every save
3. Enable Auto-sync - syncs periodically

With both enabled, you rarely need to think about syncing.

Handling Conflicts

If you edit on both devices before syncing, a conflict may occur.

When Conflicts Happen

1. HeroJournal detects the conflict
2. A dialog shows you both versions
3. Choose how to resolve:
   • Keep Local - Your current device wins
   • Keep Remote - The other device’s version wins
   • Manual Merge - Review and combine manually

Preventing Conflicts

• Sync before starting work
• Sync before switching devices
• Enable auto-sync for frequent updates
• Work on one device at a time when possible

Troubleshooting

“Authentication failed”

• Check username is correct (case-sensitive)
• Verify token hasn’t expired
• Regenerate token if needed
• Ensure token has repo scope

“Repository not found”

• Check URL is correct
• Verify you have access to the repo
• Try re-copying URL from GitHub

“Conflict detected”

• Choose which version to keep
• Or export both, compare, and merge manually
• Sync more frequently to prevent future conflicts

Sync is slow

• Large repositories take longer
• Check internet connection
• Consider archiving old achievements

Security Tips

Keep Your Data Private

• Always use private repositories
• Never share your personal access token
• Review repository access periodically

Rotate Tokens

• Set token expiration (90 days recommended)
• Create new token before old one expires
• Update both devices with new token

Review Commits

• Check commit history occasionally
• Ensure only expected changes are synced
• Revoke access if you see suspicious activity

Alternative: Manual Backup Sync

If you prefer not to use Git, you can sync manually:

1. Export from first device (Settings > Backup > Create Backup)
2. Transfer file (email, cloud storage, USB)
3. Import on second device (Settings > Backup > Import)
4. Choose Merge to combine data

This is simpler but requires manual steps each time.

Quick Reference

First-Time Setup

Daily Workflow