Git Sync

Git Sync allows you to version control your achievements using Git. This enables synchronization across devices, version history, and integration with platforms like GitHub, GitLab, or Bitbucket.

Why Use Git Sync?

• Version History - See how achievements evolved over time
• Cross-Device Sync - Keep achievements in sync between computers
• Backup - Your data is stored in a Git repository
• Restore - Roll back to any previous version
• Collaboration - Share repository with others (if desired)

Setting Up Git Sync

Prerequisites

• A Git repository (GitHub, GitLab, Bitbucket, or self-hosted)
• Repository URL (HTTPS or SSH)
• Authentication credentials (token or SSH key)

Step 1: Create a Repository

Create a new private repository on your preferred platform:

GitHub:

1. Go to github.com/new
2. Name it something like herojournal-data
3. Make it Private
4. Don’t initialize with README

GitLab:

1. Go to gitlab.com/projects/new
2. Name your project
3. Set visibility to Private

Step 2: Configure in HeroJournal

1. Go to Settings > Git tab
2. Enable Git sync with the toggle
3. Enter your repository URL
4. Choose authentication method:
   • HTTPS with token (recommended)
   • SSH (requires SSH key setup)

Step 3: Authenticate

For HTTPS (recommended):

1. Create a personal access token on your Git platform
2. Enter the token in HeroJournal
3. Click Connect

For SSH:

1. Ensure your SSH key is set up with your Git platform
2. Use the SSH URL format: git@github.com:username/repo.git
3. Click Connect

Step 4: Initial Sync

1. Click Sync Now to perform initial synchronization
2. Your achievements are now backed up to Git

Using Git Sync

Auto-Commit

When enabled, HeroJournal automatically commits changes:

• Every save creates a commit
• Commit messages describe the change
• No manual action required

Manual Sync

You can also sync manually:

• Push - Send local changes to remote
• Pull - Get changes from remote
• Sync - Both push and pull

Viewing Status

The Git panel shows:

• Current branch
• Number of commits ahead/behind
• Last sync time
• Any uncommitted changes

Syncing Across Devices

Setting Up a Second Device

1. Install HeroJournal on the new device
2. Go to Settings > Git
3. Enter the same repository URL
4. Authenticate with your credentials
5. Click Pull to download your achievements

Handling Conflicts

If you edit on multiple devices before syncing:

1. HeroJournal detects the conflict
2. You’ll be prompted to choose:
   • Keep local version
   • Keep remote version
   • Merge manually

Restoring Previous Versions

Viewing History

1. Open Git settings
2. Click View History
3. Browse previous commits

Restoring a Version

1. Find the commit you want to restore
2. Click Restore
3. Confirm the action
4. Your achievements are restored to that point

Security Considerations

Repository Privacy

• Always use private repositories
• Your achievements contain professional information
• Don’t share repository access unnecessarily

Authentication

• Use personal access tokens with minimal scope
• Rotate tokens periodically
• Don’t commit tokens to other repositories

Data Sensitivity

Consider what you include in achievements:

• Avoid including passwords or secrets
• Be mindful of confidential project information
• Remember that Git history is permanent

Troubleshooting

“Authentication failed”

• Check your token/credentials are correct
• Verify the token has appropriate permissions
• For GitHub: ensure token has repo scope

“Repository not found”

• Verify the repository URL is correct
• Check you have access to the repository
• Ensure the repository exists

“Merge conflict”

• Pull latest changes first
• Review conflicting files
• Choose which version to keep
• Commit the resolution

“Push rejected”

• Someone else pushed changes
• Pull first, then push
• Resolve any conflicts

Best Practices

1. Sync regularly - Enable auto-sync or sync daily
2. Use private repos - Protect your professional information
3. Review before push - Check what you’re committing
4. Keep tokens secure - Don’t share or expose access tokens
5. Clean history periodically - Remove sensitive data if accidentally committed