diff.go

@@ -849,7 +849,10 @@ func DiffBlobs(oldBlob *Blob, oldAsPath string, newBlob *Blob, newAsPath string,
 	return nil
 }
 
+// ApplyHunkCallback is a callback that will be made per delta (file) when applying a patch.
 type ApplyHunkCallback func(*DiffHunk) (apply bool, err error)
+
+// ApplyDeltaCallback is a callback that will be made per hunk when applying a patch.
 type ApplyDeltaCallback func(*DiffDelta) (apply bool, err error)
 
 // ApplyOptions has 2 callbacks that are called for hunks or deltas
@@ -913,6 +916,7 @@ func deltaApplyCallback(_delta *C.git_diff_delta, _payload unsafe.Pointer) C.int
 	}
 }
 
+// DefaultApplyOptions returns default options for applying diffs or patches.
 func DefaultApplyOptions() (*ApplyOptions, error) {
 	opts := C.git_apply_options{}
 
@@ -952,15 +956,26 @@ func applyOptionsFromC(opts *C.git_apply_options) *ApplyOptions {
 	}
 }
 
-type GitApplyLocation int
+// ApplyLocation represents the possible application locations for applying
+// diffs.
+type ApplyLocation int
 
 const (
-	GitApplyLocationWorkdir GitApplyLocation = C.GIT_APPLY_LOCATION_WORKDIR
-	GitApplyLocationIndex   GitApplyLocation = C.GIT_APPLY_LOCATION_INDEX
-	GitApplyLocationBoth    GitApplyLocation = C.GIT_APPLY_LOCATION_BOTH
+	// ApplyLocationWorkdir applies the patch to the workdir, leaving the
+	// index untouched. This is the equivalent of `git apply` with no location
+	// argument.
+	ApplyLocationWorkdir ApplyLocation = C.GIT_APPLY_LOCATION_WORKDIR
+	// ApplyLocationIndex applies the patch to the index, leaving the working
+	// directory untouched. This is the equivalent of `git apply --cached`.
+	ApplyLocationIndex ApplyLocation = C.GIT_APPLY_LOCATION_INDEX
+	// ApplyLocationBoth applies the patch to both the working directory and
+	// the index. This is the equivalent of `git apply --index`.
+	ApplyLocationBoth ApplyLocation = C.GIT_APPLY_LOCATION_BOTH
 )
 
-func (v *Repository) ApplyDiff(diff *Diff, location GitApplyLocation, opts *ApplyOptions) error {
+// ApplyDiff appllies a Diff to the given repository, making changes directly
+// in the working directory, the index, or both.
+func (v *Repository) ApplyDiff(diff *Diff, location ApplyLocation, opts *ApplyOptions) error {
 	runtime.LockOSThread()
 	defer runtime.UnlockOSThread()
 
@@ -976,6 +991,17 @@ func (v *Repository) ApplyDiff(diff *Diff, location GitApplyLocation, opts *Appl
 	return nil
 }
 
+// DiffFromBuffer reads the contents of a git patch file into a Diff object.
+//
+// The diff object produced is similar to the one that would be produced if you
+// actually produced it computationally by comparing two trees, however there
+// may be subtle differences. For example, a patch file likely contains
+// abbreviated object IDs, so the object IDs in a git_diff_delta produced by
+// this function will also be abbreviated.
+//
+// This function will only read patch files created by a git implementation, it
+// will not read unified diffs produced by the diff program, nor any other
+// types of patch files.
 func DiffFromBuffer(buffer []byte, repo *Repository) (*Diff, error) {
 	var diff *C.git_diff