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:
  11
  12   org.spearce.jgit/
  13
  14     A pure Java library capable of being run standalone, with no
  15     additional support libraries.  Some JUnit tests are provided
  16     to exercise the library.  The library provides functions to
  17     read and write a GIT formatted repository.
  18
  19     All portions of jgit are covered by the GPL.  Absolute no EPL
  20     contributions are accepted within this package.
  21
  22   org.spearce.egit.core/
  23
  24     An Eclipse plugin providing an interface to org.spearce.jgit
  25     and support routines to allow processing against the Eclipse
  26     workspace and resource APIs, rather than the standard Java
  27     file APIs.  It also supplies the team provider implementation.
  28
  29     Portions of this package are covered under the LGPL and others
  30     under the EPL.  Refer to individual file headers for details.
  31
  32   org.spearce.egit.ui/
  33
  34     An Eclipse plugin providing the user interface on top of
  35     org.spearce.egit.core.
  36
  37     Portions of this package are covered under the LGPL and others
  38     under the EPL.  Refer to individual file headers for details.
  39
  40   org.spearce.egit.core.test
  41
  42     Unit tests for org.spearce.egit.core.
  43
  44             == WARNINGS / CAVEATS              ==
  45
  46 - The plugin could lockup your Eclipse workbench.  I've tried to
  47   make it stable and function in such a way that it can't crash
  48   the workbench, but that doesn't mean it won't.  :-)
  49
  50 - This package might eat your files.  Everything I've added to a
  51   repository with it has unpacked properly both with itself and
  52   with the canonical C based implementation, but that doesn't mean
  53   it won't generate a corrupt object.
  54
  55 - Symbolic links are not supported because java does not support it.
  56   Such links could be damaged.
  57
  58 - It may take a long time to connect the GIT team provider to an
  59   existing project full of files as the cache tree needs to be
  60   generated from scratch.  This can take a while as most Java SHA1
  61   implementations are not exactly the fastest SHA1 implementations
  62   available.
  63
  64 - Only the timestamp of the index is used by jgit check if  the index
  65   is dirty.
  66
  67 - Don't try the plugin with a JDK other than 1.6 (Java 6) unless you
  68   are prepared to investigate problems yourself. JDK 1.5.0_11 and later
  69   Java 5 versions *may* work. Earlier versions do not. JDK 1.4 is *not*
  70   supported. Apple's Java 1.5.0_07 is reported to work acceptably. We
  71   have no information about other vendors. Please report your findings
  72   if you try.
  73
  74             == Package Features                ==
  75
  76   org.spearce.jgit/
  77
  78     * Read loose and packed commits, trees, blobs, including
  79       deltafied objects.
  80
  81     * Write loose commits, trees, blobs.
  82
  83     * Write blobs from local files or Java InputStreams.
  84
  85     * Read blobs as Java InputStreams.
  86
  87     * Copy trees to local directory, or local directory to a tree.
  88
  89     * Lazily loads trees as necessary.
  90
  91     * Read and write .git/config files.
  92
  93     * Create a new repository.
  94
  95     * Read and write refs, including walking through symrefs.
  96
  97     * Read, update and write the Git index.
  98
  99   org.spearce.egit.core/
 100
 101     * Supplies an Eclipse team provider.
 102
 103     * Connect/disconnect the provider to a project.
 104
 105     * Search for the repositories associated with a project by
 106       autodecting the GIT repository directories.
 107
 108     * Store which repositories are tied to which containers in the
 109       Eclipse workspace.
 110
 111     * Maintains a cache tree holding a snapshot of the workspace.
 112       The cache tree is diff'd against the current `HEAD` to show
 113       file status in the decorator.
 114
 115     * Runs a checkpoint job to flush the cache tree to the repository
 116       on a periodic basis.
 117
 118     * Tracks moves/renames/deletes and reflects them in the cache
 119       tree.
 120
 121     * Resolves through linked containers.
 122
 123     * Walk a the history from a given set of commits looking for commits
 124       introducing changed in a path.
 125
 126   org.spearce.egit.ui/
 127
 128     * Connect team provider wizard panels.
 129
 130     * Connect to GIT team provider by making a new repository.
 131
 132     * Connect to GIT team provider by searching local filesystem
 133       for existing repository directories.
 134
 135     * Team actions: track (add), untrack (remove), disconnect, show
 136       history, compare version, show history.
 137
 138     * Resource director shows file/directory state in the explorer
 139       various views (e.g. Navigator and Package Explorer).
 140
 141     * Creating new commits or amending commits.
 142
 143     * Graphical history viewer with the ability to compare versions
 144       using eclipse built-in compare editor.
 145
 146             == Missing Features                ==
 147
 148 - GIT network protocol to pull objects from a remote repository or
 149   push objects to a remote repository.
 150
 151 - Common base computation for a merge base.
 152
 153 - Generate a GIT format patch.
 154
 155 - Apply a GIT format patch.
 156
 157 - Documentation.  :-)
 158
 159 - Windows support is new and very little tested. Do not blame us if
 160   it blows, but tell us about it and what you did. Double check
 161   everything.
 162
 163 - gitattributes support
 164   In particular CRLF conversion is not implemented. Files are treated
 165   as byte sequences.
 166
 167 - Speed in some areas
 168   Java is "slooow", they say. Not true as a general statement. A lot of Java
 169   code is slow because it it not optimized (to some extent due to this
 170   belief). Java has quite good performance although it cannot compete with
 171   C code written by good hackers simply because C can be optimized more than
 172   Java when you actually do it and have the skills to do it. Some areas of
 173   the plugin have been optimized but not all and not conclusively. In general
 174   however Java almost always needs more memory than an application written in
 175   e.g. C. In particular there is an overhead from the rather large standard
 176   libraries that a normal Java installations comes with. See the ACM report:
 177
 178         Prechelt, L. 1999. Technical opinion: comparing Java vs. C/C++ efficiency
 179         differences to interpersonal differences. Commun. ACM 42, 10 (Oct. 1999),
 180         109-112. DOI= http://doi.acm.org/10.1145/317665.317683
 181
 182   for an interesting comparison of C, C++ and Java. It is somewhat dated so
 183   the comparison involved Java 1.2, i.e. without hotspot in 1.3 and the shared
 184   runtime in 1.4. Those features made common Java applications many times faster
 185   than with JDK 1.2.
 186
 187   The conclusion from having about 30 programmers write a program to the same
 188   specification using their own choice of language (from C,C++ and Java) is
 189   that the skills  of the programmer is what determines the performance of the
 190   code rather than choice  of programming language.
 191
 192
 193             == About GIT                       ==
 194
 195 More information about GIT, its repository format, and the canonical
 196 C based implementation can be obtained from the GIT websites:
 197
 198   http://git.or.cz/
 199   http://www.kernel.org/pub/software/scm/git/
 200   http://www.kernel.org/pub/software/scm/git/docs/