Git Sync Troubleshooting - Auk Documentation

Common Issues

Quick reference for common Git sync problems:

Authentication Failed

Symptoms:

“Permission denied (publickey)”
“Authentication failed”
“Could not read from remote repository”

Solutions:

For SSH:

# Check SSH key is loaded
ssh-add -l

# Add SSH key if not loaded
ssh-add ~/.ssh/id_ed25519

# Test SSH connection
ssh -T [email protected]

For HTTPS:

# Clear credential cache
git credential-cache exit

# Re-enter credentials on next sync

Verify Authentication:

Check SSH key is added to Git service
Verify token has correct permissions
Ensure token hasn’t expired

Push Rejected

Symptoms:

“Updates were rejected”
“Failed to push some refs”
“Non-fast-forward”

Cause: Remote has changes you don’t have locallySolution:

# Pull latest changes first
# Auk will do this automatically, but if manual:
cd ~/Library/Application\ Support/Auk/workspaces/my-workspace
git pull --rebase origin main
git push origin main

In Auk:

Click “Sync Now” to pull changes
Resolve any conflicts
Sync again to push

Merge Conflicts

Symptoms:

“Automatic merge failed”
“CONFLICT (content)”
Sync paused with conflict warning

Solution: See Conflict Resolution guideQuick steps:

Open conflict resolution UI
Choose resolution strategy
Resolve conflicts
Complete sync

Repository Not Found

Symptoms:

“Repository not found”
“Could not resolve host”
404 error

Solutions:

Verify repository URL is correct
Check you have access to repository
Ensure repository exists
Try cloning manually to test:

git clone [email protected]:username/repo.git /tmp/test

Network Timeout

Symptoms:

“Connection timed out”
“Failed to connect”
Sync hangs indefinitely

Solutions:

Check internet connection
Verify firewall isn’t blocking Git
Try different network
Increase timeout in settings:

{
  "git": {
    "syncTimeout": 300
  }
}

Detached HEAD State

Symptoms:

“You are in ‘detached HEAD’ state”
Commits not appearing on branch

Solution:

cd ~/Library/Application\ Support/Auk/workspaces/my-workspace

# Create branch from current state
git checkout -b recovery-branch

# Switch back to main
git checkout main

# Merge recovery branch if needed
git merge recovery-branch

Large File Issues

Symptoms:

“File too large”
Push fails with size error
Slow sync performance

Solutions:

Remove large files from Git:

git rm --cached large-file.json
echo "large-file.json" >> .gitignore
git commit -m "Remove large file"

Use Git LFS for large files:

git lfs install
git lfs track "*.large"

Split large collections into smaller files

Sync Stuck

Symptoms:

Sync shows “In progress” indefinitely
Cannot cancel sync
Auk becomes unresponsive

Solutions:

Wait 5 minutes for timeout
Force quit Auk if needed
Restart Auk
Check workspace Git status:

cd ~/Library/Application\ Support/Auk/workspaces/my-workspace
git status

Reset if needed:

git reset --hard origin/main

Diagnostic Commands

Check Git Status

# Navigate to workspace
cd ~/Library/Application\ Support/Auk/workspaces/my-workspace

# Check status
git status

# View recent commits
git log --oneline -10

# Check remote
git remote -v

# View branches
git branch -a

Test Connectivity

# Test SSH (GitHub)
ssh -T [email protected]

# Test SSH (GitLab)
ssh -T [email protected]

# Test SSH (Gitee)
ssh -T [email protected]

# Test HTTPS
curl -I https://github.com

View Sync Logs

macOS
Windows
Linux

# View Auk logs
tail -f ~/Library/Logs/Auk/git-sync.log

# View all logs
cat ~/Library/Logs/Auk/git-sync.log

# Search for errors
grep ERROR ~/Library/Logs/Auk/git-sync.log

# View logs
type %APPDATA%\Auk\Logs\git-sync.log

# Search for errors
findstr ERROR %APPDATA%\Auk\Logs\git-sync.log

# View logs
tail -f ~/.config/Auk/logs/git-sync.log

# Search for errors
grep ERROR ~/.config/Auk/logs/git-sync.log

Recovery Procedures

Reset to Remote State

If local state is corrupted, reset to remote:

This will discard all local changes. Backup first if needed.

cd ~/Library/Application\ Support/Auk/workspaces/my-workspace

# Backup current state
cp -r . ../my-workspace-backup

# Reset to remote
git fetch origin
git reset --hard origin/main

# Restart Auk

Recover Lost Commits

If commits are lost:

# View reflog (history of HEAD)
git reflog

# Find lost commit
# Example output:
# abc1234 HEAD@{0}: reset: moving to origin/main
# def5678 HEAD@{1}: commit: My lost changes

# Recover lost commit
git checkout def5678

# Create branch to save it
git checkout -b recovered-changes

# Merge back to main if needed
git checkout main
git merge recovered-changes

Fix Corrupted Repository

If Git repository is corrupted:

cd ~/Library/Application\ Support/Auk/workspaces/my-workspace

# Try to repair
git fsck --full

# If repair fails, re-clone
cd ..
mv my-workspace my-workspace-broken
git clone [email protected]:username/repo.git my-workspace

# Copy any uncommitted changes from broken workspace
cp my-workspace-broken/collections/*.json my-workspace/collections/

Performance Issues

Slow Sync

If sync is slow:

Check Network Speed

# Test download speed
curl -o /dev/null https://github.com/git/git/archive/refs/heads/master.zip

Enable Compression

{
  "git": {
    "compressTransfer": true
  }
}

Use Shallow Clone

For large repositories:

git clone --depth 1 [email protected]:username/repo.git

Reduce Sync Frequency

{
  "git": {
    "syncInterval": 3600
  }
}

High CPU Usage

If Git sync uses too much CPU:

{
  "git": {
    "parallelSync": false,
    "syncInterval": 1800,
    "pauseOnBattery": true
  }
}

Platform-Specific Issues

macOS

Keychain Access Denied

Symptoms: Repeated password promptsSolution:

# Update keychain helper
git config --global credential.helper osxkeychain

# Reset keychain if needed
git credential-osxkeychain erase
host=github.com
protocol=https

Xcode Command Line Tools

Symptoms: Git not found or outdatedSolution:

# Install Xcode Command Line Tools
xcode-select --install

# Verify Git version
git --version

Windows

Line Ending Issues

Symptoms: Files show as modified but no changesSolution:

# Configure line endings
git config --global core.autocrlf true

# Refresh repository
git rm --cached -r .
git reset --hard

Path Too Long

Symptoms: “Filename too long” errorSolution:

# Enable long paths
git config --global core.longpaths true

Linux

Permission Denied

Symptoms: Cannot write to workspace directorySolution:

# Fix permissions
chmod 700 ~/.config/Auk/workspaces/my-workspace
chown -R $USER ~/.config/Auk/workspaces/my-workspace

SSH Agent Not Running

Symptoms: SSH key not foundSolution:

# Start SSH agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Add to shell profile
echo 'eval "$(ssh-agent -s)"' >> ~/.bashrc
echo 'ssh-add ~/.ssh/id_ed25519' >> ~/.bashrc

Error Messages

Common Error Messages and Solutions

Error Message	Cause	Solution
`fatal: not a git repository`	Git not initialized	Initialize Git in workspace settings
`error: failed to push some refs`	Remote has newer commits	Pull before pushing
`fatal: refusing to merge unrelated histories`	Repositories have different histories	Use `--allow-unrelated-histories` flag
`error: Your local changes would be overwritten`	Uncommitted changes conflict	Commit or stash changes first
`fatal: unable to access`	Network or auth issue	Check network and credentials
`error: RPC failed; HTTP 413`	Push too large	Split into smaller commits

Getting Help

Enable Debug Logging

{
  "git": {
    "enableLogging": true,
    "logLevel": "debug"
  }
}

Collect Diagnostic Information

When reporting issues, include:

Auk Version
- Help → About Auk
Git Version
git --version
Operating System
- macOS: System Preferences → About
- Windows: Settings → System → About
- Linux: uname -a
Error Logs
- Copy from Auk logs directory

Git Status

cd workspace-directory
git status
git log --oneline -5
git remote -v

Contact Support

GitHub Issues: github.com/mamahuhu-io/auk/issues
Documentation: auk.mamahuhu.dev
Community: Join our Discord/Slack

Prevention Tips

Regular Backups

Backup workspaces regularly:

# Automated backup script
tar -czf ~/Backups/auk-$(date +%Y%m%d).tar.gz \
  ~/Library/Application\ Support/Auk/workspaces/

Test Before Production

Test Git sync with a test workspace first:

Create test workspace
Configure Git sync
Test sync operations
Verify everything works
Apply to production workspaces

Monitor Sync Status

Regularly check sync status:

Review sync history
Check for errors in logs
Verify remote repository is updated

Keep Git Updated

Use latest Git version:

# Check version
git --version

# Update (macOS with Homebrew)
brew upgrade git

# Update (Linux)
sudo apt update && sudo apt upgrade git

Next Steps

Git Sync Setup

Set up Git synchronization

Conflict Resolution

Learn conflict resolution

Best Practices

Git collaboration best practices

Support

Get additional help

​Common Issues

​For SSH:

​For HTTPS:

​Verify Authentication:

​Diagnostic Commands

​Check Git Status

​Test Connectivity

​View Sync Logs

​Recovery Procedures

​Reset to Remote State

​Recover Lost Commits

​Fix Corrupted Repository

​Performance Issues

​Slow Sync

​High CPU Usage

​Platform-Specific Issues

​macOS

​Windows

​Linux

​Error Messages

​Common Error Messages and Solutions

​Getting Help

​Enable Debug Logging

​Collect Diagnostic Information

​Contact Support

​Prevention Tips

​Next Steps

Git Sync Setup

Conflict Resolution

Best Practices

Support

Common Issues

For SSH:

For HTTPS:

Verify Authentication:

Diagnostic Commands

Check Git Status

Test Connectivity

View Sync Logs

Recovery Procedures

Reset to Remote State

Recover Lost Commits

Fix Corrupted Repository

Performance Issues

Slow Sync

High CPU Usage

Platform-Specific Issues

macOS

Windows

Linux

Error Messages

Common Error Messages and Solutions

Getting Help

Enable Debug Logging

Collect Diagnostic Information

Contact Support

Prevention Tips

Next Steps