OK. I will try to rephrase you just to make sure I understood it. GitFacet acts as a central API for the Git-related commands in a forge project. Facet methods have dependencies on jGit but they only accept and return objects from the standard Java API (like Strings, Arrays, etc) this way GitFacet is the only component with jGit dependencies. Facets neither print anything to the shell nor require user's input (ideally). Facets can modify project's state (=files) and return information about the project.

Example. (kept simple. Will probably require some more steps in between)
To create a new commit in the the git undo branch, GitFacet should provide at least the following methods:
* public List<String> getBranches() // to see if undo-branch exists or should be created first
* public String getCurrentBranch() // to see which branch we are currently working on
* public boolean changeBranch(String newBranch) // switches to the new branch (newBranch is provided by the undo plugin)
* public boolean createBranch(String newBranch) // creates a new branch
* public boolean commit(String msg) // adds all changes from the working tree to the index, and creates a git commit with a given commit message (msg is provided by the undo plugin)

the logic should be something like this:
<< forge command foo is executed, some files are modified >>

if getBranches() doesn't contain 'history-branch'
    createBranch("org.forge.history")

if currentBranch() is not "org.forge.history"
    changeBrach("org.forge.history")

commit("forge command foo was executed")

Does that sound right?

Was FORGE-183 planned as some kind of a general wrapper around jGit to provide the most common use cases?

On 04/21/2012 12:14 AM, Lincoln Baxter, III wrote:

The "Git Undo" functionality would certainly use the GitFacet, because you would only want to activate Undo support when working on a Project.

Some information about Facets:

• Facets represent project state (E.g. Git is installed. Java is installed. Servlet is installed)
  
• Facets do not work outside of projects.
• Facets avoid doing anything that prints to the shell output (sometimes it is unavoidable)
  
• Facets are for encapsulating additional functionality that is usable in one or more plugins

With that said, only some of the additional methods you suggested are not really appropriate for a Facet:

- showLatestDiff()

probably not appropriate because it would print output - this should go into the GitPlugin instead

- showLatestCommit()

Probably not appropriate because it would print output - this should go into the GitPlugin instead

- getNotes()

Not sure what this does.

- showLog()

Probably not appropriate because it would print output - this should go into the GitPlugin instead

- switchBranch()

Appropriate as an API, but not if it requires user input - this is potentially a good method and in line with being appropriate for a Facet.

- cleanWorkingDirectory()

Not exactly sure what this would do, but yes, sounds in line with being appropriate for a Facet.
 

Does that help? :)

~Lincoln

On Fri, Apr 20, 2012 at 4:52 PM, Jevgeni Zelenkov <jevgeni.zelenkov@googlemail.com> wrote:

Hi Lincoln,

Thanks for the explanation, that helped me to understand it but not
completely. So, what do you actually mean by "inspect the state of a
Project"?

I take methods provided by you:
- getBranches()
- getTags()
- getRemotes()
- getStatus()

And here are some more suggestions to help inspect the state of a project:
- showLatestDiff()
- showLatestCommit()
- getNotes()
- showLog()
- switchBranch()
- cleanWorkingDirectory()

Would that be enough?
I guess, I don't understand the use cases for the GitFacet yet.
Who is going to use it and what are the potential scenarios? The git
undo plugin will require a lot more than that. And I assume that
GitFacet is not really a wrapper for the jGit functionality.

Regards,
Jevgeni

On 04/20/2012 06:00 PM, forge-dev-request@lists.jboss.org wrote:
> Message: 5
> Date: Fri, 20 Apr 2012 09:21:10 -0400
> From: "Lincoln Baxter, III"<lincolnbaxter@gmail.com>
> Subject: Re: [forge-dev] GitPlugin Facet
> To: forge-dev List<forge-dev@lists.jboss.org>
> Message-ID:
>       <CAEp_U4GGVD8p8hH2M5PRm6gK_MkDGtAyXzokGcm3VVz70jeX2g@mail.gmail.com>
> Content-Type: text/plain; charset="iso-8859-1"
>
> Hey Jevgeni,
>
> Welcome!
>
> Regarding the GitFacet - I believe it's in the right place for the moment,
> but I don't believe that the GitPlugin should be referencing it, since the
> commands in GitPlugin could be used even without a Project.
>
> GitFacet (as the issue describes poorly) is something that should be usable
> to inspect the state of a Project via:
>
> project.hasFacet(GitFacet.class)
>
> After that, everything else is an added benefit. It should probably also
> perform tasks like:
>
> project.getFacet(GitFacet.class).getBranches()
> project.getFacet(GitFacet.class).getTags()
> project.getFacet(GitFacet.class).getRemotes()
> project.getFacet(GitFacet.class).getStatus()
>
> And that's where your imagination kicks in.
>
> Does that make sense?
>
> ~Lincoln

_______________________________________________
forge-dev mailing list
forge-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/forge-dev

--
Lincoln Baxter, III
http://ocpsoft.org
"Simpler is better."

_______________________________________________
forge-dev mailing list
forge-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/forge-dev

_______________________________________________
forge-dev mailing list
forge-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/forge-dev