Create proper exceptions

[nulltoken]

As discussed in #137 and #183, there's a need to expose reliable exceptions.

This issue is an attempt to gather feedback in order to identify pain points and recurrent errors which should lead to the creation of new exception types deriving from LibGit2SharpException.

[haacked]

Ok, I created a spreadsheet of most of the error cases that GHfW handles today. Note that we add cases as we run into them so it's by no means complete.

As much as possible, we try and report exactly what's wrong and what the user can do to fix it.

In some cases, we don't care what the specifics are, we just report a generic message. Often it's because there's not much the user can do to fix it or because we don't know why it failed. In the spreadsheet, most of those are listed as "unknown/other".

GHfW Error cases

Also, some of the errors are from us shelling to git.exe and not in libgit2. But once those features are incorporated in libgit2, it'll be good to be able to distinguish them.

[nulltoken]

@haacked That's a very useful document. Please keep it updated.

Some thoughts about it:

• GIT_EORPHANEDHEAD has recently been introduced as an error code in libgit2. Some operations already return it (cf Add error GIT_EORPHANEDHEAD libgit2#1000 and More orphaned head love libgit2#1004)
• @ethomson introduced a very cool API to identify the current state of the repository. He also added the GIT_EUNMERGED error code

The enum will certainly be exposed under Repository.Info (cf #128). This should help you identify some states and determine what operations are available or not.
The two error codes should lead to the creation of two new exceptions (maybe OrphanedHeadException and UnmergedEntriesException)

A question:

• Do you need to distinguish a missing HEAD (a repo without the HEAD symbolic reference) from an orphaned HEAD (the HEAD exists but (directly or not) points to a non existing oid reference)?

[haacked]

Hmm, good question. From a UI perspective, I think we'd only need to distinguish if the path to recovery is the same in both cases. In other words, if what we tell the user to do is the same thing, then we don't need to distinguish. Of course, we'd still want the exception message to distinguish so we can see what really happened in the log file.

What is the recovery path in these cases?

[nulltoken]

• Missing HEAD
  • Create a symbolic HEAD reference AND make it point to refs/heads/master if it exists, otherwise, the first found branch
• Orphaned HEAD
  • Switch to a branch pointing to a commit OR create a commit

[haacked]

@nulltoken Thanks! Given that the resolutions are different, yes, I think we should have different exceptions for these so we can distinguish them.

[nulltoken]

@haacked A bunch of exceptions have now been created and the repo.Info.CurrentOperation enumeration gives some insight regarding the current state of the repository.

Let's close this general purpose issue for now as we've eventually shifted as much as possible from throwing the generic LibGit2SharpException exception. Feel free to open a new issue whenever you feel you lack a proper specific exception. Cheers!