Re: [jgit-dev] JGit Client API

["Shawn O. Pearce" <spearce@xxxxxxxxxxx>]

Chris Aniszczyk <caniszczyk@xxxxxxxxx> wrote:
> On Fri, Apr 16, 2010 at 10:13 AM, Christian Halstrick
> <christian.halstrick@xxxxxxxxx> wrote:
> > - introduction of classes representing the options of a git.git
> > command: commit(CommitOptions opt) where CommitOptions has setter for
> > msg, author, committer, amend,
> 
> This is the way I would do it with some type of interface representing
> the commit options. Too many arguments are a sign that you should
> create this type of context object anyway.

Yup.

Actually, I prefer a more 'builder' style API:

  public class Git {
    public Git(Repository db);

    public CommitAction commit();
    public CheckoutAction checkout();
  }

  public class CommitAction {
    protected CommitAction(Git git);

    public CommitAction message(String message);
    public CommitAction author(PersonIdent author);
    public CommitAction committer(PersonIdent committer);
    public CommitAction signoff();

    public RevCommit amend();
    public RevCommit commit();
  }

  public class CheckoutAction {
    protected CheckoutAction(Git git);

    public CheckoutAction createBranch(String name);
    public CheckoutAction from(String revision);

    public void go();
  }


  Git g = new Git(new Repository(".git"));
  g.commit()
    .message("Save this stuff now")
    .author(new PersonIdent("Bob Jones", "bob@xxxxxxxxxxx"))
    .amend();

  g.checkout().createBranch("test").from("origin/master").go();


The only problem with this API approach is you need some logical
method at the end of the call chain that means "All options were
set, carry out the action now".

For commit I think its not too bad, we have commit() and amend()
as the obvious terminal operators.

For checkout, I'm not sure there is an obvious method, and its easy
to forget to invoke it after starting to create the options.


If you go with Chris' approach of commit(CommitOptions), I still
think the setters should all return 'this', so that chaining
is simple:

  Git g = new Git(...);
  g.commit(new CommitOptions().message("Save this stuff now")
    .author("Bob Jones", "bob@xxxxxxxxxxx")
    .amend());


What I like about the former 'builder' style I presented above is
you get to avoid the "new CommitOptions()" boilerplate in your code.
Its just annoying to write and gets in the way of what you are
really trying to do.  Its also not as easily clear you can just
chain the calls together in a single statement.


While doing this work, you might want to look at what the GitSharp
folks are doing in C#.  The language standards aren't the same,
obviously, but they are also building a wrapper around JGit to make
it easier to perform simple repository actions from "user-level"
application code.


All that said, I welcome this concept.  Its badly needed.  I'm glad
to see you are working on it.

-- 
Shawn.