Troubleshooting repository conflicts

This will concern anyone with direct commit rights to the master repository. People who do pull requests should be aware too as a matter of understanding in case you're ever granted direct commit rights.

As we've been intentionally redundant about through this documentation, you must sync the master repository to your cloned repository each time before committing changes back to master. This ensures your clone has the latest master changes from your collaborators, who committed their work before you did since last visit.

If you don't sync first, you'll likely experience a 'conflict' when you try to commit your changes. You'll know when this happens because the GitHub client will make it clear. Don't panic if/when it does. You won't have broken anything at the master end.

Troubleshoot 1: Discard out-of-sync changes

The first thing to try is undo the changes you made locally to get back to a state where you can sync with the master repo again. Fortunately, you don't have to remember what those changes were, only the files on which they happened. Do the following in your GitHub client application:

1. Get in context of your local files list.
2. Check boxes next to the local files that you changed before trying to sync with the master repo.
3. In the GitHub client menu, go to Repository > Discard Changes to Select Files... and use the option.

Each time you undo a change with the menu control, try to sync the master to see if it works. When it does, you're back in business. You will have lost whatever original changes you made before syncing, but that's the unfortunate penalty for forgetting to sync first.

Troubleshoot 2: Replace cloned repository

If you struggle to get back to a synced state with the method above, there's always the brute force solution. You can delete your local clone directory entirely using your machine's file manager, then Clone the master repository again like the first time. A fresh start. Again, you'll lose whatever changes you originally wanted to push, but at least you'll be back in working order.

One last time...

Such conflicts are easily avoided by remembering to always sync your local repo BEFORE trying to commit new changes you've made. You just get in the habit of doing that like breathing air. When you open the GitHub client, the first thing you do is hit the Sync button. This ensures any commits from other collaborators are synced down to your local clone. Click the Sync button again just before you're ready to commit any changes. The time interval between first syncing then pushing should be short.