View source for EGit/Proposal

= THIS IS A DRAFT, WORK IN PROGRESS PROPOSAL, NOT AN ACTUAL OFFICIAL ECLIPSE PROJECT PROPOSAL YET =


The EGIT project is a proposed open source project under the Eclipse Technology Project.

According to the [http://www.eclipse.org/projects/dev_process/ Eclipse Development Process], this proposal is intended to declare the intent and scope of the EGit project as well as to gather input from the Eclipse community. You are invited to comment on and/or join the project. Please send all feedback to the http://www.eclipse.org/newsportal/thread.php?group=eclipse.technology.egit newsgroup.

= Background =
Traditional source code control systems have been based around a single centralized server housing all of the project's revision history and assets.  Historically this has worked well for smaller projects, especially when all project contributors have access to the same computer system and are located in the same physical workplace.  Distributed open source projects (and commercial entities or virtual companies) have broken this model, making it much more difficult for contributors to participate.  A centralized model promotes two classes of contributors: "blessed people" (those who have access to make changes to the project and use the source code control system) and "everyone else" (the rest of the world).  Moving between classes is painful for everyone involved, and in many cases moving from "everyone else" to "blessed people" requires months of proving the contributor is trustworthy enough.

Multiple distributed version control systems (DVCS) have recently developed to fully support the truly distributed nature of modern open source projects, in particular large scale efforts such as those supported by Eclipse, Mozilla, KDE, Open Solaris, and the Linux kernel. [http://www.git-scm.org/ Git], [http://www.selenic.com/mercurial/ Mercurial], [http://www.monotone.ca/ Monotone], [http://bazaar-vcs.org/ Bazaar] and [http://darcs.net/ darcs] are all popular implementations of the DVCS concept, however their implementation details differ significantly.

True to their name, DVCS implementations eliminate the centralized server and place all project participants on an equal footing by providing them with identical capabilities.  Brand new project contributors have access to the same tools and historical data as long-term trusted contributors, making it possible for new contributors to participate on an equal footing with no risk to the overall project.  Most projects using DVCS tools flow changes from newer contributors to trusted contributors, arranging a loose hierarchy of review.

DVCS tools tend to perform better then their centralized counterparts, as network latency is only a factor when exchanging batches of new revisions.  In a DVCS the most commonly used operations such as recording changes, file comparison, history inspection, branch creation and branch merging are handled entirely offline using locally stored information, allowing these operations to complete as quickly as the disk buffer cache and CPU will permit.  Offline operation can be very useful in distributed open source projects where not all participants have large network bandwidth with low latency to connect them to the project's central server(s).  For some participants, being able to work offline may be a necessity for them to contribute, due to limited availability (or high cost) of Internet access.

= Introduction =
EGIT is an Eclipse Team provider for Git (a.k.a. "Stupid Content Tracker", http://git.or.cz).

Git is the version control system originally developed for the Linux kernel by Linus Torvalds. One of the Git strength is its ability to support distributed version tracking as well as more centralized schemes, in contrast with traditional SCM that offer only a centralized model (such as CVS and Subversion) . Git is also very fast.
Git usage has evolved beyond the Linux kernel team and is now used by many other projects -- both for open source and commercial development -- as a  fast and distributed general purposeSource Code Management (SCM) tool. 

Git is a distributed SCM, which means every developer has a full copy of all history of every revision of the code making queries against the history very fast and versatile. The storage model also means most operations are ten to a hundred times faster than with traditional centralized SCM such as CVS or Subversion. The integrity of the code is guaranteed through the use of secure hashes on the content and history, plus optional GPG/PGP key signing of tags.

= Project Description  =

The Git team provider will provide the ability to do all everyday task in a Git work flow from inside Eclipse, integrated with the Eclipse Team framework, and providing new features specific to Git and distributed version control management.

== Goal ==
The goal of the EGit project is to:
* implement an Eclipse Team provider for the Git SCM,
* work towards the definitions of new Team extensions and GUI paradigms to better support distributed SCM in general.

== Scope ==

The project will implement Eclipse tooling for the JGit Java implementation of Git. 
Specific attention will be focused on performance. Performance is a big deal with Git. It affects what can be done by being so much faster. Things that couldn't be done because of time constraints are now possible. These things like very fast checkouts, branching, branch switching, merging, tagging, software archeology and synchronization. Merge speed is probably the most important feature.
The EGit plugin meta data shall be fully compatible with the meta data created by the native Git version so both can be used on the same checkout out repository.

Beyond the Git support implementation, the project will work towards defining new essential extensions to the Eclipse core platform Team framework to account for the specific issues and features provided by distributed version control systems.
It is also our intent to reach out to other project that implement support for distributed SCM in Eclipse to collaborate and exchange in that domain.

Finally, the implications of adopting a distributed SCM approach can bring significant benefits especially for large open source projects such as Eclipse and can help lower the barrier to entry for new contributors and source code experimentation easier.
The project will try to be a fervent advocate of distributed SCM benefits to the Eclipse community.

== Features ==
* Initial project setup: Support to create new Git repositories.

* Importing existing code: Existing local Git repositories as well as remote repository can be imported. Remote repositories are imported by "cloning" them resulting in a local copy.

* Replicating repositories: It shall be possible to distribute local version to other repositories through "push" operations as well as patches distributed by electronic mail. Receiving content shall be possible by fetching content via the git supported protocols (raw, ssh and http based) and via e-mailed patches directly from mailboxes, files or clipboard. "Bundles" shall also be supported.

* Quickdiff against any version shall be supported.

* Comparing any versions shall be supported.

* Producing git-format patches to the clipboard shall be supported.

* Selective commit (using the Quickdiff markers) shall be supported

* Merge shall be supported

* Cherry picking shall be supported

* Re-base of branches shall be supported. This includes splitting, reordering and squashing (alternate term not to be confused with the normal meaning of "merge" in SCM terminology).

* Branch switching, committing, amending commits and reset shall be supported.

* Partial checkouts (currently not a native Git feature) shall be possible.

* Some form of synchronization with CVS or other SCM. At least export to CVS, like git cvsexportcommit. Ideally Git commits shall be exportable to a CVS repository with the same structure. CVS import is a much harder problem where no perfect solution exists.

=== Perspective and Views ===
* A Git perspective will be provided for browsing repositories before importing Git projects, pre-configured with available Team  views and new EGit views.
* History viewer: An history viewer with graphical presentation of history and access for compare editors will be developed as well as other views that may be useful for distributed SCM.
* Repository browser : An explorer for examining Git repositories not connected to an eclipse project. Importing projects shall be possible from here.
* Global directory: An explorer to find manage Git repositories ( at the minimum minimum all known local clones and their "remotes")

=== Extension points ===
Quickdiff must be enhanced to allow selective committing.
New extensions points will be designed as needed to expose new core extensibility common to many distributed SCM. [https://bugs.eclipse.org/134526 Bug 134526] is already discussing an extension point for quickdiff providers to contribute to the context menu.

=== Extensions to existing Eclipse Team functionality ===
Team provider
Resource decorators
Quickdiff provider


= Project Organization=
We propose this project should be undertaken as an incubator project with the Technology project.

== Mentors ==
The following members of the Eclipse Architecture Council have kindly agreed to mentor this project:

* Chris Aniszczyk
* Andrew Overholt

== Initial Committers ==
* Robin Rosenberg (project lead )
* Shawn Pearce (project lead) 
* Philippe Ombredanne
(TODO: Robin: what about others?)

== Initial Code Contribution ==
The initial code contribution is based on the existing EGit code base licensed under the EPL. 
Additionally if the project can secure approval from the Eclipse board, the JGit component will be part of the initial contribution and dual licensed under the EPL and EDL.

(TODO: Robin+ Shawn+Phil: update all copyright headers in the code and prepare review before CQ submission)

(TODO: Philippe Contact the EMO based on Wayne and Chris feedback: we could possibly get JGit @ Eclipse too under a dual EPL+BSD license, if we can get board approval. 
There is a precedent with http://eclipse.org/eclipselink which is under such a dual license using both the EPL and the EDL: 
see [http://dev.eclipse.org/svnroot/technology/org.eclipse.persistence/trunk/license.html]
see [http://www.eclipse.org/org/documents/edl-v10.php] )


=== Licensing and Intellectual property ===
A point of note is that EGit depends on the JGit, a pure Java Git implementation of Git.
JGit was originally licensed under a combination of GPL and LGPL and is now made available under a BSD style license. The developers of JGit are also the original developers of EGit.
Git itself is licensed under the GPL V2, but JGit is a clean implementation of the core Git data structures and as such has received the approval of the core Git maintainers to be licensed under any open source license the authors wish. 
Therefore the JGit authors have elected to license JGit under a BSD style license which is compatible with the Eclipse Public License and most other open source licenses.
As part of the original code contribution review, JGit will be also submitted for approval per the Eclipse development process.

(TODO: Robin+ Shawn+Phil: collate email confirmations on Git core data structure implementation and licensing including those from Linus. See [http://article.gmane.org/gmane.comp.version-control.git/81585 request thread].)

(TODO: Robin+ Shawn: we need to collate email approval from all the committers for both EGIT and JGit in a document for submission with the initial CQ)

== Interested Parties ==
(TODO: all list interested individual and companies, please add yourself  ....)

* Ismael Juma
* Neil Bartlett
* Chris Aniszczyk
* Marek Zawirski
* Cédric Brun
* Ketan Padegaonkar
* Tor Arne Vestbø
* Martin Oberhuber - related to [http://dev.eclipse.org/mhonarc/lists/e4-dev/msg00041.html e4]. Why does this proposal not link to the [http://git.or.cz/gitwiki/EclipsePlugin original Egit page] so people can look at the initial contribution? FYI we also achieved EPL+EDL dual-license board approval for DSDP-TM's TCF agent.
* Gunnar Wagenknecht
* Markus Knauer
* Antoine Toulme, Intalio Inc. (see {{bug|257706}})
* Daniel Spiewak
* Manuel Woelker

== User community ==
EGIt and JGit already have an established community and we expect that this community of users and contributors will join this new project at Eclipse. Of note is that the general support of Git on Windows is limited. By being platform neutral, EGit has the opportunity to provide advanced Git support also on this platform and serve the needs of a larger community.

== Tentative Development plan ==

Some functionality already exists, but there is no real plan at the moment for lack of committed resources. The project's rough priorities are:

Already done:

* Connect to/create repositories for exiting projects
* Create branches
* Commit
* Quickdiff against current revision
* Resources decorators for tracked and modified resources as well as repository state
* Basic compare of revisions
* Clone/fetch over git://, ssh://, http://, ftp://, sftp://, and from bundle files

Underway:
* UI for incremental fetch

Future:
* Bisecting
* Partial commits (i.e. committing partial changes)
* Comprehensive handling of different character encodings in filenames and comments.
* CRLF handling (unless we consider it unneeded)
* Bugfixes for existing code
* Formatting code for patch submission through e-mail
* Apply patch
* Rename/Copy tracking in compare revisions
* Blame (annotate)
* Merge
* Rebase
* External repository browser
* Repacking (this a really a core Git feature and the one that can be really hard or impossible to perform in Java).
* Rename tracking is an on-demand feature in git. Git does not record such information, it discovers it from content. The tight data structures in git makes implementing this in real time possible, but could still be a challenge.

The project will deliver regular milestones ...

(TODO: Robin: add rough sketch of milestones plan....)
* 2008-06-01 - Switch to BSD / EPL for jgit and egit respectively (done)
* 2008-07-01 - Fetch UI 
* 2008-08-01 - Simpler stuff like CRLF handling
* 2008-09-01 - Push (opposite of clone)
* 2008-09-01 - Local merge
* 2008-12-01 - Rename detection for compare and history

= Relation to other Eclipse projects and other open source projects =

* [http://git.or.cz Git] - The fast distributed SCM  
* JGit - a pure Java implementation of Git licensed under a BSD style license.

* Eclipse Linux project: there is natural affinity between Git and Linux, since it is the SCM of choice for the Linux kernel

* Eclipse platform team support and existing providers:
** CVS team provider
** SVN team provider

* Other DVCS projects with Eclipse plugins. We might benefit from sharing API's for certain DVCS related features
** [http://bazaar-vcs.org/BzrEclipse BzrEclipse ]
** [http://www.vectrace.com/mercurialeclipse/ Mercurial Eclipse]
** [http://eclipsedarcs.org/doku.php EclipseDarcs]

* Eclipse PDE build: to provide a Git adapter for PDE build fetching from Git repositories
**  Looks like we want an ant task for this

* Mylyn - a Task based IDE that provides privileged integration with Eclipse-supported team providers . A possible integration with EGit could be considered.

* Buckminster - A build and assembly framework. Needs to know about git to be able to clone projects