Troubleshooting Guide
Common issues and their solutions when working with dGit.
Installation Issues
Command Not Found
Problem:
-bash: dgit: command not found
Solution:
- Reinstall globally
npm uninstall -g dgit
npm install -g dgit
# Or update PATH if installed from source
export PATH="$PATH:$(npm bin -g)"
- Check npm global path:
npm config get prefix
# Add to PATH if needed
export PATH="$PATH:$(npm config get prefix)/bin"
Permission Errors
Problem:
npm ERR! Error: EACCES: permission denied
Solutions:
- Use sudo (not recommended):
sudo npm install -g dgit
- Fix npm permissions (recommended):
sudo chown -R $USER:$GROUP ~/.npm
sudo chown -R $USER:$GROUP ~/.config
Repository Issues
Invalid Repository
Problem:
Error: not a dgit repository
Solutions:
- Check current directory:
ls -la .dgit
- Initialize repository if needed:
dgit init
- Verify repository structure:
tree .dgit
Corrupt Repository
Problem:
Error: corrupt repository structure
Solutions:
- Check repository integrity:
# Verify database
ls -la .dgit/db
# Check objects
ls -la .dgit/objects
- Reinitialize if necessary:
mv .dgit .dgit_backup
dgit init
Storage Issues
Database Errors
Problem:
Error: Failed to access LevelDB database
Solutions:
- Check database lock:
rm .dgit/db/LOCK
- Verify permissions:
ls -la .dgit/db
chmod -R 755 .dgit/db
- Rebuild database:
# Backup first
cp -r .dgit/db .dgit/db_backup
rm -rf .dgit/db/*
dgit init
Disk Space Issues
Problem:
Error: no space left on device
Solutions:
- Check available space:
df -h .
- Clean unnecessary objects:
# Coming in future version
dgit gc
Commit Issues
Staging Failures
Problem:
Error: Failed to stage files
Solutions:
- Check file existence:
ls -la <file>
- Verify file permissions:
chmod 644 <file>
- Check index state:
cat .dgit/index
Commit Failures
Problem:
Error: Failed to create commit
Solutions:
- Verify staged changes:
# Future version
dgit status
- Check signing keys:
ls -la .dgit/keys
- Regenerate keys if needed:
rm .dgit/keys/*
dgit init
Performance Issues
Slow Operations
Problem: Commands taking too long to execute
Solutions:
- Check repository size:
du -sh .dgit
- Monitor system resources:
top
df -h
- Optimize storage:
# Coming in future version
dgit optimize
Debugging
Enable Debug Logging
# Set debug environment variable
export DEBUG=dgit:*
# Run command with debug output
dgit <command>
Check System Information
# Node.js version
node --version
# npm version
npm --version
# dGit version
dgit --version
Generate Debug Report
# Coming in future version
dgit debug-report
Common Error Messages
| Error Code | Message | Solution |
|---|---|---|
| E001 | Repository not found | Run dgit init |
| E002 | Invalid object hash | Check file integrity |
| E003 | Database access error | Check permissions |
| E004 | Commit signing failed | Verify keys |
| E005 | Storage full | Free disk space |
Getting Help
If you’re still experiencing issues:
- Check the GitHub Issues
- Search existing problems
- Create a new issue with:
- Error message
- Steps to reproduce
- System information
- Debug logs
Next Steps
- Review Architecture
- Check API Reference
- See Example Workflows