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.2.1 is the minimum Eclipse version. Expect this to change
  98   in future versions.
  99
 100 - Newer version of EGit/JGit may implement new functionality, remove
 101   existing functions and change others without other notice than what
 102   is written in the commit log and source files themselves.
 103
 104
 105             == Package Features                ==
 106
 107   org.spearce.jgit/
 108
 109     * Read loose and packed commits, trees, blobs, including
 110       deltafied objects.
 111
 112     * Read objects from shared repositories
 113
 114     * Write loose commits, trees, blobs.
 115
 116     * Write blobs from local files or Java InputStreams.
 117
 118     * Read blobs as Java InputStreams.
 119
 120     * Copy trees to local directory, or local directory to a tree.
 121
 122     * Lazily loads objects as necessary.
 123
 124     * Read and write .git/config files.
 125
 126     * Create a new repository.
 127
 128     * Read and write refs, including walking through symrefs.
 129
 130     * Read, update and write the Git index.
 131
 132     * Checkout in dirty working directory if trivial.
 133
 134     * Walk the history from a given set of commits looking for commits
 135       introducing changes in files under a specified path.
 136
 137   org.spearce.egit.core/
 138
 139     * Supplies an Eclipse team provider.
 140
 141     * Connect/disconnect the provider to a project.
 142
 143     * Search for the repositories associated with a project by
 144       autodecting the GIT repository directories.
 145
 146     * Store which repositories are tied to which containers in the
 147       Eclipse workspace.
 148
 149     * Tracks moves/renames/deletes and reflects them in the cache
 150       tree.
 151
 152     * Resolves through linked containers.
 153
 154   org.spearce.egit.ui/
 155
 156     * Connect team provider wizard panels.
 157
 158     * Connect to GIT team provider by making a new repository.
 159
 160     * Connect to GIT team provider by searching local filesystem
 161       for existing repository directories.
 162
 163     * Team actions: track (add), untrack (remove), disconnect, show
 164       history, compare version.
 165
 166     * Resource decorator shows file/directory state in the package
 167       explorer and other views.
 168
 169     * Creating new commits or amending commits.
 170
 171     * Graphical history viewer with the ability to compare versions
 172       using eclipse built-in compare editor.
 173
 174             == Missing Features                ==
 175
 176 There are a lot of missing features. You need the real Git for this.
 177 For some operations it may just be the preferred solution also. There
 178 are not just a command line, there is e.g. git-gui that makes committing
 179 partial files simple.
 180
 181 - GIT network protocol to pull objects from a remote repository or
 182   push objects to a remote repository.
 183
 184 - Merging.
 185
 186 - Repacking from within the plugin.
 187
 188 - Generate a GIT format patch.
 189
 190 - Apply a GIT format patch.
 191
 192 - Documentation. :-)
 193
 194 - Windows support is new and very ligthly tested. Do not blame us if
 195   it blows, but tell us about it and what you did. Double check
 196   everything.
 197
 198 - gitattributes support
 199   In particular CRLF conversion is not implemented. Files are treated
 200   as byte sequences.
 201
 202 - submodule support
 203   Submodules are not supported or even recognized.
 204
 205 - The Eclipse plugin cannot handle files outside any Eclipse project. You
 206   need commit changes to such files outside of Eclipse.
 207
 208 - Speed in some areas
 209
 210   Java is "slooow", they say. Not true as a general statement. A lot of Java
 211   code is slow because it it not optimized (to some extent due to this
 212   belief). Java has quite good performance although it cannot compete with
 213   C code written by good hackers simply because C can be optimized more than
 214   Java when you actually do it and have the skills to do it. Some areas of
 215   the plugin have been optimized but not all and not conclusively. In general
 216   however Java almost always needs more memory than an application written in
 217   e.g. C. In particular there is an overhead from the rather large standard
 218   libraries that a normal Java installation comes with. See the ACM report:
 219
 220         Prechelt, L. 1999. Technical opinion: comparing Java vs. C/C++
 221         efficiency differences to interpersonal differences. Commun. ACM 42,
 222         10 (Oct. 1999), 109-112. DOI= http://doi.acm.org/10.1145/317665.317683
 223
 224   for an interesting comparison of C, C++ and Java. It is somewhat dated so
 225   the comparison involved Java 1.2, i.e. without hotspot that appeared in Java
 226   1.3 and the shared runtime in 1.4. Those features made common Java
 227   applications many times faster than with Java 1.2
 228
 229   The conclusion from having about 30 programmers write a program to the same
 230   specification using their own choice of language (from C,C++ and Java) is
 231   that the skills of the programmer is what determines the performance of the
 232   code rather than choice of programming language.
 233
 234   JGit is much slower (measured up to eight times for some random cases), but
 235   then the real Git is ridicilously fast.
 236
 237
 238             == Support                         ==
 239
 240   Post question, comments or patches to the git@vger.kernel.org mailing list.
 241
 242
 243             == Contributing                    ==
 244
 245   See SUBMITTING_PATCHES in this directory. However, feedback and bug reports
 246   are also contributions.
 247
 248
 249             == About GIT                       ==
 250
 251 More information about GIT, its repository format, and the canonical
 252 C based implementation can be obtained from the GIT websites:
 253
 254   http://git.or.cz/
 255   http://www.kernel.org/pub/software/scm/git/
 256   http://www.kernel.org/pub/software/scm/git/docs/
 257