#Doris ##Table of contents
##License Doris is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Doris is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Doris. If not, see <http://www.gnu.org/licenses/>.
Back to top ##About Doris was created by Emil Carlsson as part of a bachelor thesis about problems encountered when mining software repositories. The main goal of the thesis was to find a mining tool that could handle git, work with as few dependencies as possible, and also provide automated reproducible extraction and measurement pipeline.
Back to top ###Recent changes
- Update to JGit 3.0 (by https://github.com/robinst)
- Optimization to mining process (by https://github.com/robinst)
- Fixed bug with not working tags.
- Added parameter object.
Back to top ###Coming updates
- Working -b flag to specify branch. At the moment only master-branch can be mined.
Back to top ###Working JARs Most common on MacOS is 1.6. To find out your JRE type java -version. ####JRE 1.7
- Version 1.1.0 (Current version)
####JRE 1.6
- Version 1.1.0 (Current version)
Back to top ##Dependencies Doris is written in Java and requires Java (JRE 1.7 or newer) to be installed on the computer running it.
Back to top ##Usage guide When using parameters and not specifying target directory, Doris will automatically create a directory with the same name as the .git file used for mining. If no parameters are passed to Doris, Doris will prompt for URI to .git file and the target to store the results from the mining. All flags are to be appended after the command to initialize Doris. When using flags the URI flag must be included as a minimum. Notice: If you have downloaded a working JAR this will have version number appended to it. Then change Doris.jar to doris-vX.Y.Z.jar to run these commands or rename jar to remove version numbering.
Run Doris on Windows:
C:\> java -jar c:\path\to\doris.jar
Run Doris on Unix-like OS:
$ java -jar doris.jar
Back to top ###Help -h, --help [flag] Shows help information. If a flag is appended it will show help information of that particular flag.
Back to top ###URI -u, --uri <link to .git-file> Specifies the URI where the .git file can be found. The protocols that Doris can handle is http(s)://, git:// and file://. Example of formatting: git://github.com/GingerSwede/Doris.git.
Back to top ###Target -t, --target Specifies the target where the different commits should be stored. When omitted Doris will use the current working directory and set up a folder named after the .git-file used in the URI.
Back to top ###Start point -s, --startpoint Set a starting point for Doris to start mining the repository from. Full sha-1 is needed. If the sha-1 value is incorrect the mining will never be started.
Back to top ###End point -e, --endpoint Set a commit where Doris should stop mining. Full sha-1 is needed. If the sha-1 value is incorrect the mining will not stop. The given sha-1 commit will not be included in the mining results.
Back to top ###Limit -l, --limit Set a maximum number of commits Doris should mine. Amount is to be given as an integer (e.g., 6, 10, 600).
Back to top ###No log -n, --nolog When this flag is passed the logging option in Doris is turned off. This is recommended when mining larger repositories that will generate many commits. All information that is logged by Doris can manually be obtained through the .git-file copied to local access. It can be found in the same directory as the mining results.
Back to top ###Important If the -e and the -l flag is used in combination Doris will end on the flags criteria that is reached first.
Back to top ##Log file Unless the -n flag is used Doris will automatically log basic information about the different commits in an xml-file. The log contain information about parent commit, author, committer, commit message and commit time (given in UNIX time). Example:
<project project_name="ExampleRepository">
<commit commit_name="08046e7b57f772f270619601d1a9420f76320066" commit_number="0" commit_time="1358168496">
<author e_mail="john.doe@example.com" name="John Doe"/>
<committer e_mail="john.doe@example.com" name="John Doe"/>
<commit_message>
Initial commit
</commit_message>
</commit>
</project>