Teach checkout to report notifications

11 files changed, 283 insertions, 44 deletions

diff --git a/LibGit2Sharp/Branch.cs b/LibGit2Sharp/Branch.cs
index 2095cc48..30baf70a 100644
--- a/LibGit2Sharp/Branch.cs
+++ b/LibGit2Sharp/Branch.cs
@@ -233,9 +233,24 @@ namespace LibGit2Sharp
         /// </summary>
         /// <param name="checkoutOptions">Options controlling checkout behavior.</param>
         /// <param name="onCheckoutProgress">Callback method to report checkout progress updates through.</param>
+        [Obsolete("This method will be removed in the next release. Please use Checkout(CheckoutOptions, CheckoutProgressHandler, CheckoutNotificationOptions) instead.")]
         public virtual void Checkout(CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress)
         {
-            repo.Checkout(this, checkoutOptions, onCheckoutProgress);
+            Checkout(checkoutOptions, onCheckoutProgress, null);
+        }
+
+        /// <summary>
+        ///   Checkout the tip commit of this <see cref = "Branch" /> object
+        ///   with a callback for progress reporting. If this commit is the
+        ///   current tip of the branch, will checkout the named branch. Otherwise,
+        ///   will checkout the tip commit as a detached HEAD.
+        /// </summary>
+        /// <param name="checkoutOptions">Options controlling checkout behavior.</param>
+        /// <param name="onCheckoutProgress">Callback method to report checkout progress updates through.</param>
+        /// <param name="checkoutNotificationOptions"><see cref="CheckoutNotificationOptions"/> to manage checkout notifications.</param>
+        public virtual void Checkout(CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress, CheckoutNotificationOptions checkoutNotificationOptions)
+        {
+            repo.Checkout(this, checkoutOptions, onCheckoutProgress, checkoutNotificationOptions);
         }
 
         private Branch ResolveTrackedBranch()
diff --git a/LibGit2Sharp/CheckoutCallbacks.cs b/LibGit2Sharp/CheckoutCallbacks.cs
index 2c3a6109..c7c14abe 100644
--- a/LibGit2Sharp/CheckoutCallbacks.cs
+++ b/LibGit2Sharp/CheckoutCallbacks.cs
@@ -11,32 +11,67 @@ namespace LibGit2Sharp
     internal class CheckoutCallbacks
     {
         /// <summary>
-        ///   Managed delegate to call in response to checkout progress_cb callback.
+        ///   The managed delegate (e.g. from library consumer) to be called in response to the checkout progress callback.
         /// </summary>
         private readonly CheckoutProgressHandler onCheckoutProgress;
 
         /// <summary>
+        ///   The managed delegate (e.g. from library consumer) to be called in response to the checkout notify callback.
+        /// </summary>
+        private readonly CheckoutNotifyHandler onCheckoutNotify;
+
+        /// <summary>
         ///   Constructor to set up native callback for given managed delegate.
         /// </summary>
         /// <param name="onCheckoutProgress"><see cref="CheckoutProgressHandler"/> delegate to call in response to checkout progress_cb</param>
-        private CheckoutCallbacks(CheckoutProgressHandler onCheckoutProgress)
+        /// <param name="onCheckoutNotify"><see cref="CheckoutNotifyHandler"/> delegate to call in response to checkout notification callback.</param>
+        private CheckoutCallbacks(CheckoutProgressHandler onCheckoutProgress, CheckoutNotifyHandler onCheckoutNotify)
         {
             this.onCheckoutProgress = onCheckoutProgress;
+            this.onCheckoutNotify = onCheckoutNotify;
         }
 
         /// <summary>
-        ///   Generate a delegate matching the signature of the native progress_cb callback and wraps the <see cref="CheckoutProgressHandler"/> delegate.
+        ///   The method to pass for the native checkout progress callback.
         /// </summary>
-        /// <param name="onCheckoutProgress"><see cref="CheckoutProgressHandler"/> that should be wrapped in the native callback.</param>
-        /// <returns>The delegate with signature matching the expected native callback. </returns>
-        internal static progress_cb GenerateCheckoutCallbacks(CheckoutProgressHandler onCheckoutProgress)
+        public progress_cb CheckoutProgressCallback
         {
-            if (onCheckoutProgress == null)
+            get
             {
+                if (this.onCheckoutProgress != null)
+                {
+                    return this.OnGitCheckoutProgress;
+                }
+
                 return null;
             }
+        }
 
-            return new CheckoutCallbacks(onCheckoutProgress).OnGitCheckoutProgress;
+        /// <summary>
+        ///   The method to pass for the native checkout notify callback.
+        /// </summary>
+        public checkout_notify_cb CheckoutNotifyCallback
+        {
+            get
+            {
+                if (this.onCheckoutNotify != null)
+                {
+                    return this.OnGitCheckoutNotify;
+                }
+
+                return null;
+            }
+        }
+
+        /// <summary>
+        ///   Generate a delegate matching the signature of the native progress_cb callback and wraps the <see cref="CheckoutProgressHandler"/> delegate.
+        /// </summary>
+        /// <param name="onCheckoutProgress"><see cref="CheckoutProgressHandler"/> that should be wrapped in the native callback.</param>
+        /// <param name="onCheckoutNotify"><see cref="CheckoutNotifyHandler"/> delegate to call in response to checkout notification callback.</param>
+        /// <returns>The delegate with signature matching the expected native callback. </returns>
+        internal static CheckoutCallbacks GenerateCheckoutCallbacks(CheckoutProgressHandler onCheckoutProgress, CheckoutNotifyHandler onCheckoutNotify)
+        {
+            return new CheckoutCallbacks(onCheckoutProgress, onCheckoutNotify);
         }
 
         /// <summary>
@@ -48,10 +83,31 @@ namespace LibGit2Sharp
         /// <param name="payload">Payload object.</param>
         private void OnGitCheckoutProgress(IntPtr str, UIntPtr completedSteps, UIntPtr totalSteps, IntPtr payload)
         {
-            // Convert null strings into empty strings.
-            string path = (str != IntPtr.Zero) ? Utf8Marshaler.FromNative(str) : string.Empty;
+            if (onCheckoutProgress != null)
+            {
+                // Convert null strings into empty strings.
+                string path = (str != IntPtr.Zero) ? Utf8Marshaler.FromNative(str) : string.Empty;
+
+                onCheckoutProgress(path, (int)completedSteps, (int)totalSteps);
+            }
+        }
+
+        private int OnGitCheckoutNotify(
+            CheckoutNotifyFlags why,
+            IntPtr pathPtr,
+            IntPtr baselinePtr,
+            IntPtr targetPtr,
+            IntPtr workdirPtr,
+            IntPtr payloadPtr)
+        {
+            int result = 0;
+            if (this.onCheckoutNotify != null)
+            {
+                string path = (pathPtr != IntPtr.Zero) ? FilePathMarshaler.FromNative(pathPtr).Native : string.Empty;
+                result = onCheckoutNotify(path, why) ? 0 : 1;
+            }
 
-            onCheckoutProgress(path, (int)completedSteps, (int)totalSteps);
+            return result;
         }
     }
 }
diff --git a/LibGit2Sharp/CheckoutNotificationOptions.cs b/LibGit2Sharp/CheckoutNotificationOptions.cs
new file mode 100644
index 00000000..18819373
--- /dev/null
+++ b/LibGit2Sharp/CheckoutNotificationOptions.cs
@@ -0,0 +1,82 @@
+using LibGit2Sharp.Handlers;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+
+namespace LibGit2Sharp
+{
+    /// <summary>
+    ///   Flags controlling checkout notification behavior.
+    /// </summary>
+    [Flags]
+    public enum CheckoutNotifyFlags
+    {
+
+        /// <summary>
+        ///   No checkout notification.
+        /// </summary>
+        None = 0, /* GIT_CHECKOUT_NOTIFY_NONE */
+
+        /// <summary>
+        ///   Notify on conflicting paths.
+        /// </summary>
+        Conflict = (1 << 0), /* GIT_CHECKOUT_NOTIFY_CONFLICT */
+
+        /// <summary>
+        ///   Notify about dirty files. These are files that do not need
+        ///   an update, but no longer match the baseline.
+        /// </summary>
+        Dirty = (1 << 1), /* GIT_CHECKOUT_NOTIFY_DIRTY */
+
+        /// <summary>
+        ///   Notify for files that will be updated.
+        /// </summary>
+        Updated = (1 << 2), /* GIT_CHECKOUT_NOTIFY_UPDATED */
+
+        /// <summary>
+        ///   Notify for untracked files.
+        /// </summary>
+        Untracked = (1 << 3), /* GIT_CHECKOUT_NOTIFY_UNTRACKED */
+
+        /// <summary>
+        ///   Notify about ignored file.
+        /// </summary>
+        Ignored = (1 << 4), /* GIT_CHECKOUT_NOTIFY_IGNORED */
+    }
+
+    /// <summary>
+    ///   Class to specify options and callback on CheckoutNotifications.
+    /// </summary>
+    public class CheckoutNotificationOptions
+    {
+        /// <summary>
+        ///   Needed for mocking purposes.
+        /// </summary>
+        protected CheckoutNotificationOptions()
+        {
+        }
+
+        /// <summary>
+        ///   The delegate that will be called for files that match the
+        ///   options specified in NotifyFlags.
+        /// </summary>
+        public virtual CheckoutNotifyHandler CheckoutNotifyHandler { get; private set; }
+
+        /// <summary>
+        ///   The Flags specifying what notifications are reported.
+        /// </summary>
+        public virtual CheckoutNotifyFlags NotifyFlags { get; private set; }
+
+        /// <summary>
+        ///   Construct the CheckoutNotificationOptions class.
+        /// </summary>
+        /// <param name="checkoutNotifyHandler"><see cref = "CheckoutNotifyHandler" /> that checkout notifications are reported through.</param>
+        /// <param name="notifyFlags">The checkout notification type.</param>
+        public CheckoutNotificationOptions(CheckoutNotifyHandler checkoutNotifyHandler, CheckoutNotifyFlags notifyFlags)
+        {
+            CheckoutNotifyHandler = checkoutNotifyHandler;
+            NotifyFlags = notifyFlags;
+        }
+    }
+}
diff --git a/LibGit2Sharp/Core/Ensure.cs b/LibGit2Sharp/Core/Ensure.cs
index d09ec616..63d7dcab 100644
--- a/LibGit2Sharp/Core/Ensure.cs
+++ b/LibGit2Sharp/Core/Ensure.cs
@@ -55,6 +55,9 @@ namespace LibGit2Sharp.Core
 
             switch (result)
             {
+                case (int) GitErrorCode.User:
+                    throw new UserCancelledException(errorMessage, (GitErrorCode)result, error.Category);
+
                 case (int)GitErrorCode.BareRepo:
                     throw new BareRepositoryException(errorMessage, (GitErrorCode)result, error.Category);
 
diff --git a/LibGit2Sharp/Core/GitCheckoutOpts.cs b/LibGit2Sharp/Core/GitCheckoutOpts.cs
index 159ba581..6d1fac33 100644
--- a/LibGit2Sharp/Core/GitCheckoutOpts.cs
+++ b/LibGit2Sharp/Core/GitCheckoutOpts.cs
@@ -1,5 +1,6 @@
 using System;
 using System.Runtime.InteropServices;
+using LibGit2Sharp.Handlers;
 
 namespace LibGit2Sharp.Core
 {
@@ -80,19 +81,8 @@ namespace LibGit2Sharp.Core
         GIT_CHECKOUT_UPDATE_SUBMODULES_IF_CHANGED = (1 << 17),
     }
 
-    [Flags]
-    internal enum NotifyFlags
-    {
-        GIT_CHECKOUT_NOTIFY_NONE = 0,
-        GIT_CHECKOUT_NOTIFY_CONFLICT = (1 << 0),
-        GIT_CHECKOUT_NOTIFY_DIRTY = (1 << 1),
-        GIT_CHECKOUT_NOTIFY_UPDATED = (1 << 2),
-        GIT_CHECKOUT_NOTIFY_UNTRACKED = (1 << 3),
-        GIT_CHECKOUT_NOTIFY_IGNORED = (1 << 4),
-    }
-
     internal delegate int checkout_notify_cb(
-        NotifyFlags why,
+        CheckoutNotifyFlags why,
         IntPtr path,
         IntPtr baseline,
         IntPtr target,
@@ -117,7 +107,7 @@ namespace LibGit2Sharp.Core
         public uint FileMode;
         public int FileOpenFlags;
 
-        public NotifyFlags notify_flags;
+        public CheckoutNotifyFlags notify_flags;
         public checkout_notify_cb notify_cb;
         public IntPtr notify_payload;
 
diff --git a/LibGit2Sharp/Handlers.cs b/LibGit2Sharp/Handlers.cs
index eb2dc03f..8194d80c 100644
--- a/LibGit2Sharp/Handlers.cs
+++ b/LibGit2Sharp/Handlers.cs
@@ -1,4 +1,6 @@
-namespace LibGit2Sharp.Handlers
+using System;
+
+namespace LibGit2Sharp.Handlers
 {
     /// <summary>
     ///   Delegate definition to handle Progress callback.
@@ -48,6 +50,14 @@
     public delegate void CheckoutProgressHandler(string path, int completedSteps, int totalSteps);
 
     /// <summary>
+    ///   Delegate definition for checkout notification callback.
+    /// </summary>
+    /// <param name="path">The path the callback corresponds to.</param>
+    /// <param name="notifyFlags">The checkout notification type.</param>
+    /// <returns>True to continue checkout operation; false to cancel checkout operation.</returns>
+    public delegate bool CheckoutNotifyHandler(string path, CheckoutNotifyFlags notifyFlags);
+
+    /// <summary>
     ///   Delegate definition for unmatched path callback.
     ///   <para>
     ///     This callback will be called to notify the caller of unmatched path.
diff --git a/LibGit2Sharp/IRepository.cs b/LibGit2Sharp/IRepository.cs
index 6e3faea5..e73d0f7b 100644
--- a/LibGit2Sharp/IRepository.cs
+++ b/LibGit2Sharp/IRepository.cs
@@ -82,18 +82,52 @@ namespace LibGit2Sharp
         /// <param name="checkoutOptions"><see cref = "CheckoutOptions" /> controlling checkout behavior.</param>
         /// <param name="onCheckoutProgress"><see cref = "CheckoutProgressHandler" /> that checkout progress is reported through.</param>
         /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
+        [Obsolete("This method will be removed in the next release. Please use Checkout(Branch, CheckoutOptions, CheckoutProgressHandler, CheckoutNotificationOptions) instead.")]
         Branch Checkout(Branch branch, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress);
 
         /// <summary>
+        ///   Checkout the commit pointed at by the tip of the specified <see cref = "Branch" />.
+        ///   <para>
+        ///     If this commit is the current tip of the branch as it exists in the repository, the HEAD
+        ///     will point to this branch. Otherwise, the HEAD will be detached, pointing at the commit sha.
+        ///   </para>
+        /// </summary>
+        /// <param name="branch">The <see cref = "Branch" /> to check out. </param>
+        /// <param name="checkoutOptions"><see cref = "CheckoutOptions" /> controlling checkout behavior.</param>
+        /// <param name="onCheckoutProgress"><see cref = "CheckoutProgressHandler" /> that checkout progress is reported through.</param>
+        /// <param name="checkoutNotificationOptions"><see cref="CheckoutNotificationOptions"/> to manage checkout notifications.</param>
+        /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
+        Branch Checkout(Branch branch, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress, CheckoutNotificationOptions checkoutNotificationOptions);
+
+        /// <summary>
         ///   Checkout the specified branch, reference or SHA.
+        ///   <para>
+        ///     If the committishOrBranchSpec parameter resolves to a branch name, then the checked out HEAD will
+        ///     will point to the branch. Otherwise, the HEAD will be detached, pointing at the commit sha.
+        ///   </para>
         /// </summary>
         /// <param name = "committishOrBranchSpec">A revparse spec for the commit or branch to checkout.</param>
         /// <param name="checkoutOptions">Options controlling checkout behavior.</param>
         /// <param name="onCheckoutProgress">Callback method to report checkout progress updates through.</param>
-        /// <returns>The new HEAD.</returns>
+        /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
+        [Obsolete("This method will be removed in the next release. Please use Checkout(string, CheckoutOptions, CheckoutProgressHandler, CheckoutNotificationOptions) instead.")]
         Branch Checkout(string committishOrBranchSpec, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress);
 
         /// <summary>
+        ///   Checkout the specified branch, reference or SHA.
+        ///   <para>
+        ///     If the committishOrBranchSpec parameter resolves to a branch name, then the checked out HEAD will
+        ///     will point to the branch. Otherwise, the HEAD will be detached, pointing at the commit sha.
+        ///   </para>
+        /// </summary>
+        /// <param name = "committishOrBranchSpec">A revparse spec for the commit or branch to checkout.</param>
+        /// <param name="checkoutOptions">Options controlling checkout behavior.</param>
+        /// <param name="onCheckoutProgress">Callback method to report checkout progress updates through.</param>
+        /// <param name="checkoutNotificationOptions"><see cref="CheckoutNotificationOptions"/> to manage checkout notifications.</param>
+        /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
+        Branch Checkout(string committishOrBranchSpec, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress, CheckoutNotificationOptions checkoutNotificationOptions);
+
+        /// <summary>
         ///   Checkout the specified <see cref = "Commit" />.
         ///   <para>
         ///     Will detach the HEAD and make it point to this commit sha.
@@ -102,8 +136,9 @@ namespace LibGit2Sharp
         /// <param name="commit">The <see cref = "Commit" /> to check out. </param>
         /// <param name="checkoutOptions"><see cref = "CheckoutOptions" /> controlling checkout behavior.</param>
         /// <param name="onCheckoutProgress"><see cref = "CheckoutProgressHandler" /> that checkout progress is reported through.</param>
+        /// <param name="checkoutNotificationOptions"><see cref="CheckoutNotificationOptions"/> to manage checkout notifications.</param>
         /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
-        Branch Checkout(Commit commit, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress);
+        Branch Checkout(Commit commit, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress, CheckoutNotificationOptions checkoutNotificationOptions);
 
         /// <summary>
         ///   Try to lookup an object by its <see cref = "ObjectId" />. If no matching object is found, null will be returned.
diff --git a/LibGit2Sharp/LibGit2Sharp.csproj b/LibGit2Sharp/LibGit2Sharp.csproj
index 50b4c697..4d74e4f1 100644
--- a/LibGit2Sharp/LibGit2Sharp.csproj
+++ b/LibGit2Sharp/LibGit2Sharp.csproj
@@ -66,6 +66,7 @@
     <Compile Include="BranchUpdater.cs" />
     <Compile Include="Changes.cs" />
     <Compile Include="CheckoutCallbacks.cs" />
+    <Compile Include="CheckoutNotificationOptions.cs" />
     <Compile Include="CheckoutOptions.cs" />
     <Compile Include="CompareOptions.cs" />
     <Compile Include="Core\HistoryRewriter.cs" />
diff --git a/LibGit2Sharp/Repository.cs b/LibGit2Sharp/Repository.cs
index b85d0993..6f2c3757 100644
--- a/LibGit2Sharp/Repository.cs
+++ b/LibGit2Sharp/Repository.cs
@@ -539,6 +539,8 @@ namespace LibGit2Sharp
             RepositoryOptions options = null,
             Credentials credentials = null)
         {
+            CheckoutCallbacks checkoutCallbacks = CheckoutCallbacks.GenerateCheckoutCallbacks(onCheckoutProgress, null);
+
             var cloneOpts = new GitCloneOptions
                 {
                     Bare = bare ? 1 : 0,
@@ -547,7 +549,7 @@ namespace LibGit2Sharp
                         {
                             version = 1,
                             progress_cb =
-                                CheckoutCallbacks.GenerateCheckoutCallbacks(onCheckoutProgress),
+                                checkoutCallbacks.CheckoutProgressCallback,
                             checkout_strategy = checkout
                                                     ? CheckoutStrategy.GIT_CHECKOUT_SAFE_CREATE
                                                     : CheckoutStrategy.GIT_CHECKOUT_NONE
@@ -572,24 +574,46 @@ namespace LibGit2Sharp
 
         /// <summary>
         ///   Checkout the specified <see cref = "Branch" />, reference or SHA.
+        ///   <para>
+        ///     If the committishOrBranchSpec parameter resolves to a branch name, then the checked out HEAD will
+        ///     will point to the branch. Otherwise, the HEAD will be detached, pointing at the commit sha.
+        ///   </para>
         /// </summary>
         /// <param name = "committishOrBranchSpec">A revparse spec for the commit or branch to checkout.</param>
         /// <param name="checkoutOptions"><see cref = "CheckoutOptions" /> controlling checkout behavior.</param>
         /// <param name="onCheckoutProgress"><see cref = "CheckoutProgressHandler" /> that checkout progress is reported through.</param>
         /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
+        [Obsolete("This method will be removed in the next release. Please use Checkout(string, CheckoutOptions, CheckoutProgressHandler, CheckoutNotificationOptions) instead.")]
         public Branch Checkout(string committishOrBranchSpec, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress)
         {
+            return Checkout(committishOrBranchSpec, checkoutOptions, onCheckoutProgress, null);
+        }
+
+        /// <summary>
+        ///   Checkout the specified <see cref = "Branch" />, reference or SHA.
+        ///   <para>
+        ///     If the committishOrBranchSpec parameter resolves to a branch name, then the checked out HEAD will
+        ///     will point to the branch. Otherwise, the HEAD will be detached, pointing at the commit sha.
+        ///   </para>
+        /// </summary>
+        /// <param name = "committishOrBranchSpec">A revparse spec for the commit or branch to checkout.</param>
+        /// <param name="checkoutOptions"><see cref = "CheckoutOptions" /> controlling checkout behavior.</param>
+        /// <param name="onCheckoutProgress"><see cref = "CheckoutProgressHandler" /> that checkout progress is reported through.</param>
+        /// <param name="checkoutNotifications"><see cref="CheckoutNotificationOptions"/> to manage checkout notifications.</param>
+        /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
+        public Branch Checkout(string committishOrBranchSpec, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress, CheckoutNotificationOptions checkoutNotifications)
+        {
             Ensure.ArgumentNotNullOrEmptyString(committishOrBranchSpec, "committishOrBranchSpec");
 
             Branch branch = TryResolveBranch(committishOrBranchSpec);
 
             if (branch != null)
             {
-                return Checkout(branch, checkoutOptions, onCheckoutProgress);
+                return Checkout(branch, checkoutOptions, onCheckoutProgress, checkoutNotifications);
             }
 
             Commit commit = LookupCommit(committishOrBranchSpec);
-            CheckoutTree(commit.Tree, checkoutOptions, onCheckoutProgress, commit.Id.Sha, committishOrBranchSpec, committishOrBranchSpec != "HEAD");
+            CheckoutTree(commit.Tree, checkoutOptions, onCheckoutProgress, checkoutNotifications, commit.Id.Sha, committishOrBranchSpec, committishOrBranchSpec != "HEAD");
 
             return Head;
         }
@@ -622,8 +646,24 @@ namespace LibGit2Sharp
         /// <param name="checkoutOptions"><see cref = "CheckoutOptions" /> controlling checkout behavior.</param>
         /// <param name="onCheckoutProgress"><see cref = "CheckoutProgressHandler" /> that checkout progress is reported through.</param>
         /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
+        [Obsolete("This method will be removed in the next release. Please use Checkout(Branch, CheckoutOptions, CheckoutProgressHandler, CheckoutNotificationOptions) instead.")]
         public Branch Checkout(Branch branch, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress)
         {
+            return Checkout(branch, checkoutOptions, onCheckoutProgress, null);
+        }
+
+        /// <summary>
+        ///   Checkout the tip commit of the specified <see cref = "Branch" /> object. If this commit is the
+        ///   current tip of the branch, will checkout the named branch. Otherwise, will checkout the tip commit
+        ///   as a detached HEAD.
+        /// </summary>
+        /// <param name="branch">The <see cref = "Branch" /> to check out. </param>
+        /// <param name="checkoutOptions"><see cref = "CheckoutOptions" /> controlling checkout behavior.</param>
+        /// <param name="onCheckoutProgress"><see cref = "CheckoutProgressHandler" /> that checkout progress is reported through.</param>
+        /// <param name="checkoutNotificationOptions"><see cref="CheckoutNotificationOptions"/> to manage checkout notifications.</param>
+        /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
+        public Branch Checkout(Branch branch, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress, CheckoutNotificationOptions checkoutNotificationOptions)
+        {
             Ensure.ArgumentNotNull(branch, "branch");
 
             // Make sure this is not an unborn branch.
@@ -640,11 +680,11 @@ namespace LibGit2Sharp
                 string.Equals(Refs[branch.CanonicalName].TargetIdentifier, branch.Tip.Id.Sha,
                 StringComparison.OrdinalIgnoreCase))
             {
-                CheckoutTree(branch.Tip.Tree, checkoutOptions, onCheckoutProgress, branch.CanonicalName, branch.Name, !branchIsCurrentRepositoryHead);
+                CheckoutTree(branch.Tip.Tree, checkoutOptions, onCheckoutProgress, checkoutNotificationOptions, branch.CanonicalName, branch.Name, !branchIsCurrentRepositoryHead);
             }
             else
             {
-                CheckoutTree(branch.Tip.Tree, checkoutOptions, onCheckoutProgress, branch.Tip.Id.Sha, branch.Name, !branchIsCurrentRepositoryHead);
+                CheckoutTree(branch.Tip.Tree, checkoutOptions, onCheckoutProgress, checkoutNotificationOptions, branch.Tip.Id.Sha, branch.Name, !branchIsCurrentRepositoryHead);
             }
 
             return Head;
@@ -659,11 +699,12 @@ namespace LibGit2Sharp
         /// <param name="commit">The <see cref = "LibGit2Sharp.Commit" /> to check out. </param>
         /// <param name="checkoutOptions"><see cref = "CheckoutOptions" /> controlling checkout behavior.</param>
         /// <param name="onCheckoutProgress"><see cref = "CheckoutProgressHandler" /> that checkout progress is reported through.</param>
+        /// <param name="checkoutNotificationOptions"><see cref="CheckoutNotificationOptions"/> to manage checkout notifications.</param>
         /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
-        public Branch Checkout(Commit commit, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress)
+        public Branch Checkout(Commit commit, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress, CheckoutNotificationOptions checkoutNotificationOptions)
         {
-            CheckoutTree(commit.Tree, checkoutOptions, onCheckoutProgress, commit.Id.Sha, commit.Id.Sha, true);
-            
+            CheckoutTree(commit.Tree, checkoutOptions, onCheckoutProgress, checkoutNotificationOptions, commit.Id.Sha, commit.Id.Sha, true);
+
             return Head;
         }
 
@@ -683,19 +724,26 @@ namespace LibGit2Sharp
         /// <param name="tree">The <see cref="Tree"/> to checkout.</param>
         /// <param name="checkoutOptions"><see cref = "CheckoutOptions" /> controlling checkout behavior.</param>
         /// <param name="onCheckoutProgress"><see cref = "CheckoutProgressHandler" /> that checkout progress is reported through.</param>
+        /// <param name="checkoutNotificationOptions"><see cref="CheckoutNotificationOptions"/> to manage checkout notifications.</param>
         /// <param name="headTarget">Target for the new HEAD.</param>
         /// <param name="refLogHeadSpec">The spec which will be written as target in the reflog.</param>
         /// <param name="writeReflogEntry">Will a reflog entry be created.</param>
-        private void CheckoutTree(Tree tree, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress,
+        private void CheckoutTree(Tree tree, CheckoutOptions checkoutOptions, CheckoutProgressHandler onCheckoutProgress, CheckoutNotificationOptions checkoutNotificationOptions,
             string headTarget, string refLogHeadSpec, bool writeReflogEntry)
         {
             var previousHeadName = Info.IsHeadDetached ? Head.Tip.Sha : Head.Name;
 
-            var options = new GitCheckoutOpts
+            CheckoutNotifyHandler onCheckoutNotify = checkoutNotificationOptions != null ? checkoutNotificationOptions.CheckoutNotifyHandler : null;
+            CheckoutNotifyFlags checkoutNotifyFlags = checkoutNotificationOptions != null ? checkoutNotificationOptions.NotifyFlags : default(CheckoutNotifyFlags);
+            CheckoutCallbacks checkoutCallbacks = CheckoutCallbacks.GenerateCheckoutCallbacks(onCheckoutProgress, onCheckoutNotify);
+
+            GitCheckoutOpts options = new GitCheckoutOpts
             {
                 version = 1,
                 checkout_strategy = CheckoutStrategy.GIT_CHECKOUT_SAFE,
-                progress_cb = CheckoutCallbacks.GenerateCheckoutCallbacks(onCheckoutProgress)
+                progress_cb = checkoutCallbacks.CheckoutProgressCallback,
+                notify_cb = checkoutCallbacks.CheckoutNotifyCallback,
+                notify_flags = checkoutNotifyFlags
             };
 
             if (checkoutOptions.HasFlag(CheckoutOptions.Force))
diff --git a/LibGit2Sharp/RepositoryExtensions.cs b/LibGit2Sharp/RepositoryExtensions.cs
index 262d1d91..9eb2c6d0 100644
--- a/LibGit2Sharp/RepositoryExtensions.cs
+++ b/LibGit2Sharp/RepositoryExtensions.cs
@@ -256,7 +256,7 @@ namespace LibGit2Sharp
         /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
         public static Branch Checkout(this IRepository repository, string commitOrBranchSpec)
         {
-            return repository.Checkout(commitOrBranchSpec, CheckoutOptions.None, null);
+            return repository.Checkout(commitOrBranchSpec, CheckoutOptions.None, null, null);
         }
 
         /// <summary>
@@ -271,7 +271,7 @@ namespace LibGit2Sharp
         /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
         public static Branch Checkout(this IRepository repository, Branch branch)
         {
-            return repository.Checkout(branch, CheckoutOptions.None, null);
+            return repository.Checkout(branch, CheckoutOptions.None, null, null);
         }
 
         /// <summary>
@@ -285,7 +285,7 @@ namespace LibGit2Sharp
         /// <returns>The <see cref = "Branch" /> that was checked out.</returns>
         public static Branch Checkout(this IRepository repository, Commit commit)
         {
-            return repository.Checkout(commit, CheckoutOptions.None, null);
+            return repository.Checkout(commit, CheckoutOptions.None, null, null);
         }
 
         internal static string BuildRelativePathFrom(this Repository repo, string path)
diff --git a/LibGit2Sharp/UserCanceledException.cs b/LibGit2Sharp/UserCanceledException.cs
index d451824b..43bc6b7d 100644
--- a/LibGit2Sharp/UserCanceledException.cs
+++ b/LibGit2Sharp/UserCanceledException.cs
@@ -5,8 +5,7 @@ using LibGit2Sharp.Core;
 namespace LibGit2Sharp
 {
     /// <summary>
-    ///   The exception that is thrown when an operation which requires a
-    ///   working directory is performed against a bare repository.
+    ///   The exception that is thrown when an operation is canceled.
     /// </summary>
     [Serializable]
     public class UserCancelledException : LibGit2SharpException