3 files changed, 7 insertions, 3 deletions
diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index 0bac5690a..b4f9ad081 100644
--- a/include/git2/checkout.h
+++ b/include/git2/checkout.h
@@ -81,7 +81,8 @@ typedef struct git_checkout_opts {
  * @param repo repository to check out (must be non-bare)
  * @param opts specifies checkout options (may be NULL)
  * @param stats structure through which progress information is reported
- * @return 0 on success, GIT_ERROR otherwise (use giterr_last for information
+ * @return 0 on success, GIT_EORPHANEDHEAD when HEAD points to a non existing
+ * branch, GIT_ERROR otherwise (use giterr_last for information
  * about the error)
  */
 GIT_EXTERN(int) git_checkout_head(
diff --git a/include/git2/errors.h b/include/git2/errors.h
index 1c4e910a6..38b7fe0ae 100644
--- a/include/git2/errors.h
+++ b/include/git2/errors.h
@@ -27,6 +27,7 @@ enum {
 	GIT_EBUFS = -6,
 	GIT_EUSER = -7,
 	GIT_EBAREREPO = -8,
+	GIT_EORPHANEDHEAD = -9,
 
 	GIT_PASSTHROUGH = -30,
 	GIT_ITEROVER = -31,
diff --git a/include/git2/repository.h b/include/git2/repository.h
index 025a0a95d..32a2f6449 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -272,7 +272,8 @@ GIT_EXTERN(int) git_repository_init_ext(
  * @param head_out pointer to the reference which will be retrieved
  * @param repo a repository object
  *
- * @return 0 on success; error code otherwise
+ * @return 0 on success, GIT_EORPHANEDHEAD when HEAD points to a non existing
+ * branch, an error code otherwise
  */
 GIT_EXTERN(int) git_repository_head(git_reference **head_out, git_repository *repo);
 
@@ -562,7 +563,8 @@ GIT_EXTERN(int) git_repository_set_head_detached(
  * Otherwise, the HEAD will be detached and point to the peeled Commit.
  *
  * @param repo Repository pointer
- * @return 0 on success, or an error code
+ * @return 0 on success, GIT_EORPHANEDHEAD when HEAD points to a non existing
+ * branchor an error code
  */
 GIT_EXTERN(int) git_repository_detach_head(
 	git_repository* repo);