Skip to main content

​
Understanding Conflicts

Conflicts occur when multiple team members modify the same part of a collection or environment simultaneously.

​
When Conflicts Happen

Same File Modified

Two people edit the same collection file

Same Request Changed

Different changes to the same API request

Concurrent Deletions

One person deletes while another modifies

Environment Variables

Conflicting environment variable changes

​
Conflict Detection

Auk detects conflicts during sync: 
Sync Process:
1. Commit local changes ✓
2. Pull remote changes ✓
3. Merge changes... ⚠️  Conflict detected!

   Conflicts in:
   - collections/user-api.json
   - environments/development.json

​
Conflict Notification

When conflicts are detected:
  1. Sync Pauses - Auto-sync stops
  2. Notification - Desktop notification appears
  3. Status Indicator - Shows conflict warning
  4. Conflict Panel - Opens automatically

​
Conflict Resolution UI

Auk provides a visual interface for resolving conflicts: 
┌─────────────────────────────────────────────────────────┐
│ Conflict Resolution                                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│ File: collections/user-api.json                         │
│ Request: POST /users                                    │
│                                                         │
│ ┌─────────────────────┐  ┌─────────────────────┐      │
│ │   Your Changes      │  │  Remote Changes     │      │
│ ├─────────────────────┤  ├─────────────────────┤      │
│ │ {                   │  │ {                   │      │
│ │   "method": "POST", │  │   "method": "POST", │      │
│ │   "endpoint": "/u", │  │   "endpoint": "/u", │      │
│ │   "body": {         │  │   "body": {         │      │
│ │     "name": "req"   │  │     "username": ""  │      │
│ │   }                 │  │   }                 │      │
│ │ }                   │  │ }                   │      │
│ └─────────────────────┘  └─────────────────────┘      │
│                                                         │
│ Resolution:                                             │
│ ○ Keep Your Changes                                     │
│ ○ Use Remote Changes                                    │
│ ● Smart Merge (Recommended)                             │
│ ○ Manual Edit                                           │
│                                                         │
│ [Cancel]  [Resolve Conflict]                            │
└─────────────────────────────────────────────────────────┘

​
Resolution Strategies

Automatically combines non-conflicting changes:
1

Analyze Changes

Auk analyzes both versions to identify conflicts
2

Auto-Merge Safe Changes

Non-conflicting changes are merged automatically:
  • New requests added by both sides
  • Different properties modified
  • Independent changes
3

Highlight Conflicts

Only true conflicts require manual resolution:
  • Same property changed differently
  • Conflicting deletions
4

Apply Merge

Merged result is saved and committed
Example: 
// Your changes: Added "email" field
{
  "name": "required",
  "email": "required"
}

// Remote changes: Added "phone" field
{
  "name": "required",
  "phone": "optional"
}

// Smart merge result: Both fields included
{
  "name": "required",
  "email": "required",
  "phone": "optional"
}

​
2. Keep Your Changes

Use your local version, discarding remote changes:
This will overwrite team members’ changes. Use only when you’re certain your version is correct.
When to use:
  • You know remote changes are incorrect
  • You’ve discussed with team and agreed
  • Remote changes were accidental

​
3. Use Remote Changes

Accept remote version, discarding your local changes:
This will discard your local changes. Ensure you don’t need them before proceeding.
When to use:
  • Remote changes are more up-to-date
  • You want to start fresh with team’s version
  • Your local changes were experimental

​
4. Manual Edit

Manually edit the conflicting file:
1

Open in Editor

Click “Edit Manually” to open the file
2

Review Conflict Markers

Git adds conflict markers to the file:
{
  "endpoint": "/users",
<<<<<<< HEAD (Your changes)
  "body": {
    "name": "required"
  }
=======
  "body": {
    "username": "required"
  }
>>>>>>> remote (Remote changes)
}
3

Resolve Conflicts

Edit the file to resolve conflicts:
{
  "endpoint": "/users",
  "body": {
    "username": "required",
    "name": "required"
  }
}
4

Mark as Resolved

Save the file and mark conflict as resolved

​
Conflict Types

​
Collection Conflicts

Scenario: Two people modify the same collection
Conflict:
  • Person A: Changed request method to PUT
  • Person B: Changed request endpoint
Resolution:
  • Smart merge: Apply both changes
  • Result: PUT request with new endpoint

​
Environment Conflicts

Scenario: Environment variables changed differently
Conflict:
  • Person A: baseUrl = "http://localhost:3000"
  • Person B: baseUrl = "http://localhost:8080"
Resolution:
  • Prompt user to choose correct value
  • Or keep both in different environments

​
Preventing Conflicts

​
Best Practices

Reduce conflict likelihood by syncing often:
{
  "git": {
    "autoSync": true,
    "syncInterval": 300  // 5 minutes
  }
}
Coordinate with team before major changes:
  • Announce in team chat before editing
  • Use feature branches for large changes
  • Assign ownership of collections
Organize collections by ownership:
collections/
├── auth/           # Alice owns
├── users/          # Bob owns
└── payments/       # Carol owns
Create branches for major changes:
# Create feature branch
git checkout -b feature/new-endpoints

# Work on changes
# Merge back when ready
Always pull latest changes before starting work:
  • Sync at start of day
  • Sync before making changes
  • Sync before switching tasks

​
Workspace Organization

Structure workspaces to minimize conflicts: 
Option 1: By Feature
├── workspace-auth/
├── workspace-payments/
└── workspace-users/

Option 2: By Environment
├── workspace-dev/
├── workspace-staging/
└── workspace-prod/

Option 3: By Team Member
├── workspace-alice/
├── workspace-bob/
└── workspace-shared/

​
Conflict Resolution Workflow

Complete workflow for handling conflicts:
1

Conflict Detected

Auk detects conflict during sync and pauses
2

Review Changes

Open conflict resolution UI and review both versions
3

Choose Strategy

Select resolution strategy:
  • Smart merge (recommended)
  • Keep local
  • Use remote
  • Manual edit
4

Resolve Conflict

Apply chosen strategy and verify result
5

Test Changes

Test the merged result to ensure it works
6

Complete Sync

Mark conflict as resolved and complete sync
7

Notify Team

Inform team about resolution if needed

​
Advanced Scenarios

​
Multiple Conflicts

When multiple files have conflicts:
  1. Resolve One by One - Auk presents conflicts sequentially
  2. Batch Resolution - Apply same strategy to all (if appropriate)
  3. Skip and Return - Skip difficult conflicts, resolve easy ones first

​
Recurring Conflicts

If same conflicts keep appearing:
  1. Identify Root Cause - Why are same files conflicting?
  2. Reorganize - Split collections or use branches
  3. Coordinate - Establish team conventions
  4. Automate - Use conflict resolution rules

​
Complex Merges

For complex conflicts:
  1. Export Both Versions - Save local and remote versions
  2. Manual Merge - Use external diff tool
  3. Import Result - Import merged version back
  4. Verify - Test thoroughly before committing

​
Troubleshooting

Symptoms: Resolution fails or creates errorsSolutions:
  • Export both versions for manual review
  • Check JSON syntax is valid
  • Restore from backup if needed
  • Contact team to coordinate resolution
Symptoms: Conflict detected but no UI appearsSolutions:
  • Check notification settings
  • Manually open conflict panel
  • Review sync logs for details
  • Restart Auk if needed
Symptoms: Same conflict appears after resolutionSolutions:
  • Ensure resolution was committed
  • Check sync completed successfully
  • Verify remote has your changes
  • May need to force push (with caution)

​
Next Steps

Auto Sync

Configure automatic synchronization

Troubleshooting

Solve common Git sync issues

Best Practices

Learn Git collaboration best practices

Workspace Organization

Organize workspaces to prevent conflicts