Embedding JGit presentation slides from EclipseCon Europe 2013.

1. Embedding JGit
Alex Blewitt
@alblue

2. Level Zero
• JGit is a command line-program
• java -jar jgit.sh ...
JGit.sh is a shell script
./jgit.sh ...
•
with an additional
• System.getRuntime().exec(“java -jar jgit.sh”)
!
Not ‘embedded’ - but useful for memory
constrained or GC sensitive applications

3. Level Zero
•
Advantages
•
Disadvantages
•
You already know
how to use this
•
No re-use between
runs
•
No new commands
needed
•
Spawns a new JVM
each time
•
•
Simple
•
Have to parse the
results via text stream
Useful if in-process
memory is limited

4. Level One
• The jgit command line processor is in the
‘pgm’ jar and can be invoked directly
• org.eclipse.jgit.pgm.Main.
main(new String[] {...})
• --git-dir /path/to/.git ls-tree HEAD
• --git-dir /path/to/.git show HEAD

5. Level One
•
•
•
•
•
•
•
•
•
•
•
•
•
•
add
archive
blame
branch
checkout
clone
commit
config
daemon
diff
diff-tree
fetch
gc
glog
•
•
•
•
•
•
•
•
•
•
•
•
•
•
init
log
ls-remote
ls-tree
merge
push
reflog
reset
rev-list
rev-parse
rm
show
show-ref
status

6. Level One
•
Advantages
•
•
•
Easy to remember
Uses existing
commands
In-process allows for
repeated runs
•
Disadvantages
•
•
•
High level
Have to parse output
Does not allow for
optimisations
between runs

7. Level Two
• Create/use Git and built-in porcelain
commands
• Git git = org.eclipse.jgit.api.Git.
open(new File(“/path/to/.git”))
• git.clean()
• git.log()
• git.lsRemote()

8. Level Two
• Commands use builder pattern
• git.clean().setCleanDirectories(true).
setIgnore(true).call()
• git.lsRemote().setRemote().setTags(true).
setHeads(true).call()
i
Builder pattern allows for new
‘arguments’ to be added over time

9. Level Two
•
Advantages
•
•
Allows commands to
be compile-time
checked
Does not involve text
processing
•
Can interpret/process
results
•
Can invoke many
commands on repo
•
Disadvantages
•
Required arguments
may be missing
•
Limited to provided
command API
•
May be more optimal
to go deeper in some
cases

10. Level Three
• Work directly with the repository
• repository = FileRepositoryBuilder.create(
new File(“...”))
• builder also handles cases like GIT_
environment variables and .git in parent
directories
• Repository provides object and ref
databases

11. Level Three
• repository.getTags()
• repository.getAllRefs()
• repository.getBranch() (current branch)
• repository.getRef(...)
• HEAD = repository.getRef(“HEAD”)
• repository.open(HEAD.getObjectId()).
copyTo(System.out)

12. Level Three
•
Advantages
•
Disadvantages
•
Can use caches like
RepositoryCache
•
Limited direct API on
repository
•
Can work with/
update references
directly
•
Have to work with
lower level APIs

13. Level Four
• Repositories are processed by walkers
• Git repository content
• References point to Commits (and tags,refs)
• Commits point to Commits and Trees
• Trees point to Trees and Blobs
• Think of it as a Commit Iterator (RevWalk) or
Directory/File Iterator (TreeWalk)

14. Level Four
RevWalk rw = new RevWalk(repository);
HEAD = repository.resolve(“HEAD”)
rw.markStart(rw.parseCommit(HEAD))
Iterator<RevCommit> it = rw.iterator()
while(it.hasNext())
RevCommit commit = it.next()
System.out.println(
commit.abbreivate(6) .name() + “ ” +
commit.getShortMessage())

15. Level Four
TreeWalk tw = new TreeWalk(repository);
tree = repository.resolve(“HEAD^{tree}”)
tw.addTree(tree) // tree ‘0’
tw.setRecursive(true)
tw.setFilter(PathFilter.create(“some/file”))
while(tw.next())
id = tw.getObjectId(0)
repository.open(id).copyTo(System.out)

16. Level Four
•
Advantages
•
Disadvantages
•
Can construct
complex filters
•
Lacks a simple API to
‘get this file’
•
Can walk commits
between ranges
•
Seems confusing at
first
•
Can walk multiple
trees at once (e.g. for
diffing)
•
Dispose to release
resources before reuse
!
Walkers are not thread safe, so create
separate ones if needed

17. Level Five
• ObjectInserter and ObjectReader are used
to put and get data from repositories
• id = repository.newObjectInserter(
Constants.OJB_BLOB,
“hello world”.getBytes(“UTF-8”))
• repository.newObjectReader().open(id).
copyTo(System.out)

18. Level Five
•
Advantages
•
•
Ultimate flexibility
•
Use a ‘notes-like’
approach to store
additional metadata
Can store any
content needed
•
Disadvantages
•
•
Complex to use
Need to build trees
and commits to
prevent being garbage
collected

19. Levels of Embedding
0. System.exec(“java -jar jgit.sh ...”)
1. Main.main([]“--git-dir”, “/path/.git”, “...”)
2. Git.open(new File(“.../.git”)).clean().call()
3. FileRepositoryBuilder.create(...).getRef()
4. new TreeWalk/RevWalk(repository)
5. repository.newObjectInserter/Reader

20. Thankyou
Alex Blewitt
@alblue
Winners of Eclipse 4 Plug-in development
Lorenzo Bettini
Vincenzo Caselli
@lorenzo_bettini
@vcaselli