Apache POI - Source Code Repository

Most users of the source code probably don't need to have day to day access to the source code as it changes. Therefore most users will want to make use of our source release packages, which contain the complete source tree for each binary release, suitable for browsing or debugging. These source releases are available from our download page.

The Apache POI source code is also available as source artifacts in the Maven Central repository, which may be helpful for those users who make use of POI via Maven and wish to inspect the source (eg when debugging in an IDE).

For general information on connecting to the ASF Subversion, repositories, see the version control page.

Apache POI uses Subversion as its version control system, but also has a read-only git mirror

NOTE: When checking out a subproject using subversion, either perform a sparse checkout or check out the trunk or a single branch or tag to avoid filling up your hard-disk and wasting bandwidth.

• For read only access to the latest Apache POI code, please use https://svn.apache.org/repos/asf/poi/trunk/
• To browse the svn repository in your web browser, please use ViewVC

If you are not a Committer, but you want to submit patches or even request commit privileges, please see our Contribution Guidelines for more information.

The master source repository for Apache POI is the Subversion one listed above. To support those users and developers who prefer to use the Git tooling, read-only access to the POI source tree is also available via Git. The Git mirrors normally track SVN to within a few minutes.

The official read-only Git repository for Apache POI is available from git.apache.org/ . The Git Clone URL is: git://git.apache.org/poi.git and Https Clone URL: https://git.apache.org/poi.git . Please see the Git at Apache page for more details on the service.

In addition to the git.apache.org repository, changes are also mirrored in near-realtime to GitHub. The GitHub repository is available at https://github.com/apache/poi . Please note that the GitHub repository is read-only, but pull requests sent to it will result in an email being sent to the mailing list. A Git-formatted patch added to Bugzilla is generally preferred though, as it can be tracked along with all the other contributions. Please see the contribution guidelines for more information on getting involved in the project.

Git provides a nice functionality "git-svn" which allows to read the history of a Subversion repository and convert it into a full Git repository. This will keep information from the SVN revisions so that the Git repository can be updated with newer revisions from Subversion as well as allowing to push commits from Git "upstream" into the Subversion repository. See the official documentation for more details.

The git-svn functionality is provided as a set of sub-commands to "git svn". To start retrieving information from SVN and create the initial Git repository run the following command:

            git svn clone https://svn.apache.org/repos/asf/poi/trunk poisvngit --revision 1732982:HEAD
            

Running without --revision from:HEAD will run for a long time and will retrieve the full version history of the Subversion repository. If you need more repository history, change the from revision to an earlier release or omit the --revision specifier altogether.

When this finishes you have a Git repository whose "master" branch mirrors the SVN "trunk".
From here you can use the full power of Git, i.e. quick branching, rebasing, merging, ...
See below for some common usage hints.

In order to fetch the latest SVN revisions, you need to "rebase" onto the SVN trunk:

            git checkout master
            git svn rebase
            

This will fetch the latest changes from Subversion and will rebase the master-branch onto them.

The following command will push all changes on master back to Subversion:

            git svn dcommit
            

Note that usually all commits on master will be sent to Subversion in one go, so it's similar to a "push" to another Git repository. The dcommit may fail if there are newer revisions in Subversion, you will need to run a git svn rebase first in this case.

Although you can use the full power of Git, there are a few things that work well and some things that will get you into trouble:

You should not develop on master, rather use some branching concept where you do work on sub-branches and only merge/cherry-pick the changes that are ready for being sent upstream. It seems to work better to constantly rebase changes onto the master branch as this will keep the history clean compared to the SVN repository and will avoid sending useless "Merge" commits to Subversion.

You can keep some changes that are only useful locally by using two branches that are rebased onto each other. E.g. something like the following has proven to work well:

            master
                -> localchanges - commits that should not be sent upstream ->
                    -> workbranch - place for doing development work
            

When things are ready in the workbranch do a

            git co master
            git cherry-pick commitid ...
            

to get all the finished commits onto master as preparation for pushing them upstream. Then you can git svn dcommit to send the changes upstream and a git svn rebase to get master updated with the newly created SVN revisions. Finally do the following to update both branches onto the new SVN head

            # rebase you local changes onto the latest SVN state
            git checkout localchanges
            git rebase master

            # also set the working branch to the latest state from SVN.
            git checkout workbranch
            git rebase workbranch
            

Sounds like too much work? Put these steps into a small script and all this will become a simple poiupdate to get all branches rebased onto HEAD from Subversion.

Code quality reports for Apache POI are available on the Apache Sonar instance.

Sonar provides lots of useful numbers and statistics, especially watching the project over time shows how some of the indicators evolve and allows to see which areas need some polishing.