Git Sync Troubleshooting

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

Getting Started

Core Concepts

Workspace Management

Git Sync

API Testing

Features

Data Management

Desktop Client

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

Getting Started

Core Concepts

Workspace Management

Git Sync

API Testing

Features

Data Management

Desktop Client

​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