README

   1             == Java GIT and Eclipse GIT plugin ==
   2
   3 Parts of this package are licensed under the BSD, and others are
   4 licensed under the EPL.  Please refer to the COPYING and LICENSE
   5 files for the complete licenses within each package, and please
   6 refer to the individual source file header to determine
   7 which license covers it.
   8
   9
  10 This package is actually composed of three major components plus
  11 three for packaging.
  12
  13   org.spearce.jgit/
  14
  15     A pure Java library capable of being run standalone, with no
  16     additional support libraries.  Some JUnit tests are provided
  17     to exercise the library.  The library provides functions to
  18     read and write a GIT formatted repository.
  19
  20     All portions of jgit are covered by the BSD.  Absolutely no GPL,
  21     LGPL or EPL contributions are accepted within this package.
  22
  23   org.spearce.jgit.test/
  24     Unit tests for org.spearce.jgit and the same licensing rules.
  25
  26   org.spearce.egit.core/
  27
  28     An Eclipse plugin providing an interface to org.spearce.jgit
  29     and support routines to allow processing against the Eclipse
  30     workspace and resource APIs, rather than the standard Java
  31     file APIs.  It also supplies the team provider implementation.
  32     Everything here is EPL.
  33
  34   org.spearce.egit.ui/
  35
  36     An Eclipse plugin providing the user interface on top of
  37     org.spearce.egit.core.
  38
  39     Everything here is EPL.
  40
  41   org.spearce.egit.core.test/
  42
  43     Unit tests for org.spearce.egit.core.
  44
  45     Everything here is EPL.
  46
  47   org.spearce.egit/
  48
  49     A plugin for packaging
  50
  51     Everything here is EPL.
  52
  53   org.spearce.egit-feature
  54
  55     Also packaging. This project is for building an Eclipse "feature"
  56     out of the plugins above.
  57
  58     Everything here is EPL.
  59
  60   org.spearce.egit-updatesite/
  61
  62     This package is for producing and update site, i.e. a web site
  63     you can point your eclipse at and just upgrade.
  64
  65     Everything here is EPL.
  66
  67             == WARNINGS / CAVEATS              ==
  68
  69 - The plugin could lockup your Eclipse workbench.  I've tried to
  70   make it stable and function in such a way that it can't crash
  71   the workbench, but that doesn't mean it won't.  :-)
  72
  73 - This package might eat your files.  Everything I've added to a
  74   repository with it has unpacked properly both with itself and
  75   with the canonical C based implementation, but that doesn't mean
  76   it won't generate a corrupt object.
  77
  78 - Symbolic links are not supported because java does not support it.
  79   Such links could be damaged.
  80
  81 - Only the timestamp of the index is used by jgit check if  the index
  82   is dirty.
  83
  84 - Don't try the plugin with a JDK other than 1.6 (Java 6) unless you
  85   are prepared to investigate problems yourself. JDK 1.5.0_11 and later
  86   Java 5 versions *may* work. Earlier versions do not. JDK 1.4 is *not*
  87   supported. Apple's Java 1.5.0_07 is reported to work acceptably. We
  88   have no information about other vendors. Please report your findings
  89   if you try.
  90
  91 - Do not trust this plugin to always do the right thing (yet). Please
  92   check with the real Git and report any problems.
  93
  94
  95             == COMPATIBILITY                   ==
  96
  97 - Eclipse 3.3.1 is the minimum Eclipse version, 3.4 is preferred.
  98
  99 - Newer version of EGit/JGit may implement new functionality, remove
 100   existing functions and change others without other notice than what
 101   is written in the commit log and source files themselves.
 102
 103
 104             == Package Features                ==
 105
 106   org.spearce.jgit/
 107
 108     * Read loose and packed commits, trees, blobs, including
 109       deltafied objects.
 110
 111     * Read objects from shared repositories
 112
 113     * Write loose commits, trees, blobs.
 114
 115     * Write blobs from local files or Java InputStreams.
 116
 117     * Read blobs as Java InputStreams.
 118
 119     * Copy trees to local directory, or local directory to a tree.
 120
 121     * Lazily loads objects as necessary.
 122
 123     * Read and write .git/config files.
 124
 125     * Create a new repository.
 126
 127     * Read and write refs, including walking through symrefs.
 128
 129     * Read, update and write the Git index.
 130
 131     * Checkout in dirty working directory if trivial.
 132
 133     * Walk the history from a given set of commits looking for commits
 134       introducing changes in files under a specified path.
 135
 136   org.spearce.egit.core/
 137
 138     * Supplies an Eclipse team provider.
 139
 140     * Connect/disconnect the provider to a project.
 141
 142     * Search for the repositories associated with a project by
 143       autodecting the GIT repository directories.
 144
 145     * Store which repositories are tied to which containers in the
 146       Eclipse workspace.
 147
 148     * Tracks moves/renames/deletes and reflects them in the cache
 149       tree.
 150
 151     * Resolves through linked containers.
 152
 153   org.spearce.egit.ui/
 154
 155     * Connect team provider wizard panels.
 156
 157     * Connect to GIT team provider by making a new repository.
 158
 159     * Connect to GIT team provider by searching local filesystem
 160       for existing repository directories.
 161
 162     * Team actions: track (add), untrack (remove), disconnect, show
 163       history, compare version.
 164
 165     * Resource decorator shows file/directory state in the package
 166       explorer and other views.
 167
 168     * Creating new commits or amending commits.
 169
 170     * Graphical history viewer with the ability to compare versions
 171       using eclipse built-in compare editor.
 172
 173             == Missing Features                ==
 174
 175 There are a lot of missing features. You need the real Git for this.
 176 For some operations it may just be the preferred solution also. There
 177 are not just a command line, there is e.g. git-gui that makes committing
 178 partial files simple.
 179
 180 - Merging.
 181
 182 - Repacking from within the plugin.
 183
 184 - Generate a GIT format patch.
 185
 186 - Apply a GIT format patch.
 187
 188 - Documentation. :-)
 189
 190 - Windows support is new and very ligthly tested. Do not blame us if
 191   it blows, but tell us about it and what you did. Double check
 192   everything.
 193
 194 - gitattributes support
 195   In particular CRLF conversion is not implemented. Files are treated
 196   as byte sequences.
 197
 198 - submodule support
 199   Submodules are not supported or even recognized.
 200
 201 - The Eclipse plugin cannot handle files outside any Eclipse project. You
 202   need commit changes to such files outside of Eclipse.
 203
 204 - Speed in some areas
 205
 206   Java is "slooow", they say. Not true as a general statement. A lot of Java
 207   code is slow because it it not optimized (to some extent due to this
 208   belief). Java has quite good performance although it cannot compete with
 209   C code written by good hackers simply because C can be optimized more than
 210   Java when you actually do it and have the skills to do it. Some areas of
 211   the plugin have been optimized but not all and not conclusively. In general
 212   however Java almost always needs more memory than an application written in
 213   e.g. C. In particular there is an overhead from the rather large standard
 214   libraries that a normal Java installation comes with. See the ACM report:
 215
 216         Prechelt, L. 1999. Technical opinion: comparing Java vs. C/C++
 217         efficiency differences to interpersonal differences. Commun. ACM 42,
 218         10 (Oct. 1999), 109-112. DOI= http://doi.acm.org/10.1145/317665.317683
 219
 220   for an interesting comparison of C, C++ and Java. It is somewhat dated so
 221   the comparison involved Java 1.2, i.e. without hotspot that appeared in Java
 222   1.3 and the shared runtime in 1.4. Those features made common Java
 223   applications many times faster than with Java 1.2
 224
 225   The conclusion from having about 30 programmers write a program to the same
 226   specification using their own choice of language (from C,C++ and Java) is
 227   that the skills of the programmer is what determines the performance of the
 228   code rather than choice of programming language.
 229
 230   JGit is much slower (measured up to eight times for some random cases), but
 231   then the real Git is ridicilously fast.
 232
 233
 234             == Support                         ==
 235
 236   Post question, comments or patches to the git@vger.kernel.org mailing list.
 237
 238
 239             == Contributing                    ==
 240
 241   See SUBMITTING_PATCHES in this directory. However, feedback and bug reports
 242   are also contributions.
 243
 244
 245             == About GIT                       ==
 246
 247 More information about GIT, its repository format, and the canonical
 248 C based implementation can be obtained from the GIT websites:
 249
 250   http://git.or.cz/
 251   http://www.kernel.org/pub/software/scm/git/
 252   http://www.kernel.org/pub/software/scm/git/docs/
 253