Worktree.AddWithOptions: improve documentation and interface

Author: mcuadros

Diff for: options.go

@@ -2,6 +2,7 @@ package git
 
 import (
 	"errors"
+	"fmt"
 	"regexp"
 	"strings"
 	"time"
@@ -375,8 +376,26 @@ var (
 
 // AddOptions describes how a add operation should be performed
 type AddOptions struct {
-	All  bool
+	// All equivalent to `git add -A`, update the index not only where the
+	// working tree has a file matching `Path` but also where the index already
+	// has an entry. This adds, modifies, and removes index entries to match the
+	// working tree.  If no `Path` nor `Glob` is given when `All` option is
+	// used, all files in the entire working tree are updated.
+	All bool
+	// Path is the exact filepath to a the file or directory to be added.
 	Path string
+	// Glob adds all paths, matching pattern, to the index. If pattern matches a
+	// directory path, all directory contents are added to the index recursively.
+	Glob string
+}
+
+// Validate validates the fields and sets the default values.
+func (o *AddOptions) Validate(r *Repository) error {
+	if o.Path != "" && o.Glob != "" {
+		return fmt.Errorf("fields Path and Glob are mutual exclusive")
+	}
+
+	return nil
 }
 
 // CommitOptions describes how a commit operation should be performed.

Diff for: worktree_status.go

@@ -265,6 +265,7 @@ func diffTreeIsEquals(a, b noder.Hasher) bool {
 // the worktree to the index. If any of the files is already staged in the index
 // no error is returned. When path is a file, the blob.Hash is returned.
 func (w *Worktree) Add(path string) (plumbing.Hash, error) {
+	// TODO(mcuadros): deprecate in favor of AddWithOption in v6.
 	return w.doAdd(path, make([]gitignore.Pattern, 0))
 }
 
@@ -308,16 +309,33 @@ func (w *Worktree) doAddDirectory(idx *index.Index, s Status, directory string,
 	return
 }
 
-// add changes from all tracked and untracked files
-func (w *Worktree) AddWithOptions(opts *AddOptions) (plumbing.Hash, error) {
+// AddWithOptions file contents to the index,  updates the index using the
+// current content found in the working tree, to prepare the content staged for
+// the next commit.
+//
+// It typically adds the current content of existing paths as a whole, but with
+// some options it can also be used to add content with only part of the changes
+// made to the working tree files applied, or remove paths that do not exist in
+// the working tree anymore.
+func (w *Worktree) AddWithOptions(opts *AddOptions) error {
+	if err := opts.Validate(w.r); err != nil {
+		return err
+	}
+
 	if opts.All {
-		return w.doAdd(".", w.Excludes)
+		_, err := w.doAdd(".", w.Excludes)
+		return err
 	}
-	return w.Add(opts.Path)
+
+	if opts.Glob != "" {
+		return w.AddGlob(opts.Glob)
+	}
+
+	_, err := w.Add(opts.Path)
+	return err
 }
 
 func (w *Worktree) doAdd(path string, ignorePattern []gitignore.Pattern) (plumbing.Hash, error) {
-	// TODO(mcuadros): remove plumbing.Hash from signature at v5.
 	s, err := w.Status()
 	if err != nil {
 		return plumbing.ZeroHash, err
@@ -353,6 +371,7 @@ func (w *Worktree) doAdd(path string, ignorePattern []gitignore.Pattern) (plumbi
 // directory path, all directory contents are added to the index recursively. No
 // error is returned if all matching paths are already staged in index.
 func (w *Worktree) AddGlob(pattern string) error {
+	// TODO(mcuadros): deprecate in favor of AddWithOption in v6.
 	files, err := util.Glob(w.Filesystem, pattern)
 	if err != nil {
 		return err

Diff for: worktree_test.go

@@ -1396,7 +1396,7 @@ func (s *WorktreeSuite) TestAddAll(c *C) {
 	w.Excludes = make([]gitignore.Pattern, 0)
 	w.Excludes = append(w.Excludes, gitignore.ParsePattern("file3", nil))
 
-	_, err = w.AddWithOptions(&AddOptions{All: true})
+	err = w.AddWithOptions(&AddOptions{All: true})
 	c.Assert(err, IsNil)
 
 	idx, err = w.r.Storer.Index()
@@ -1437,7 +1437,7 @@ func (s *WorktreeSuite) TestAddGlob(c *C) {
 	err = util.WriteFile(w.Filesystem, "qux/bar/baz", []byte("BAZ"), 0755)
 	c.Assert(err, IsNil)
 
-	err = w.AddGlob(w.Filesystem.Join("qux", "b*"))
+	err = w.AddWithOptions(&AddOptions{Glob: w.Filesystem.Join("qux", "b*")})
 	c.Assert(err, IsNil)
 
 	idx, err = w.r.Storer.Index()