README

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