Coming

Coming is a tool for commit analysis in git repositories.

If you use Coming, please cite:

• Coming: a Tool for Mining Change Pattern Instances from Git Commits. M. Martinez, M. Monperrus, Proceedings of ICSE, 2019 (doi:10.1109/ICSE-Companion.2019.00043). bibtex

Contact:

Matias Martinez, Martin Monperrus

Install

Coming is deployed on Maven Central, see past versions.

To build yourself, the procedure is as follows.

Add a github token in .m2/settings.xml.

<settings>
  <servers>
    <server>
      <id>brufulascam</id>
      <username>yourlogin</username>
      <!-- your github token with scope read:packages -->
      <password>FOOBAR</password>
    </server>
  </servers>
</settings>

Install a JDK 17 and configure Maven or your IDE to use it.

$ export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64/
$ mvn -version
Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.9, vendor: Private Build, runtime: /usr/lib/jvm/java-17-openjdk-amd64

# now installing
$ mvn install -DskipTests

Tests:

git clone https://github.com/SpoonLabs/repogit4testv0
mvn test

repogit4testv0 is a GIT repository included inside Coming which is used by the test cases.

Run with main class

The main class is: fr.inria.coming.main.ComingMain.

mvn exec:java -Dexec.mainClass=fr.inria.coming.main.ComingMain

 -action <INS | DEL | UPD | MOV | PER | ANY>                          tye of action to be mined
 -branch <branch name>                                                In case of -input='git', use this branch name. Default is master.
 -entitytype <arg>                                                    entity type to be mine
 -entityvalue <arg>                                                   the value of the entity  mentioned in -entitytype
 -filter <arg>                                                        name of the filter
 -filtervalue <arg>                                                   values of the filter  mentioned in -filter
 -hunkanalysis <arg>                                                  include analysis of hunks
 -input <git(default) | files | filespair | repairability>            format of the content present in the given -path. git implies that the path is a git repository. files implies the path contains .patch files
 -location <path>                                                     analyse the content in 'path'
 -message <arg>                                                       comming message
 -mode <mineinstance | diff | features>                               the mode of execution of the analysis
 -output <path>                                                       dump the output of the analysis in the given path
 -outputprocessor <classname>                                         output processors for result
 -parameters <arg>                                                    Parameters, divided by :
 -parentlevel <arg>                                                   numbers of AST node where the parent is located. 1 implies immediate parent
 -parenttype <arg>                                                    parent type of the nodes to be considered
 -pattern <path>                                                      path of the pattern file to be used when the -mode is 'mineinstance'
 -patternparser <classname>                                           parser to be used for parsing the file specified -pattern. Default is XML
 -repairtool <ALL | JMutRepair | Nopol | JKali | NPEfix | JGenProg>   If -mode=repairability, this option specifies which repair tools should we consider in our analysis. Can be a list separated by :
 -showactions                                                         show all actions
 -showentities                                                        show all entities

Parameters Most of the properties are configured in file config-coming.properties

One can change any of those properties from the command line by using -parameters

The value of those argument are the following format <name_property_1>:<value_property_1>:<name_property_2>:<value_property_2>

In the following command we change the value of two properties: max_nb_hunks and max_files_per_commit

   -parameters max_nb_hunks:2:max_files_per_commit:1

Modes

Mode Instance Mining

When running Coming in mode -mode mineinstance the output is a file name instances_found.json , which shows the different instances of the pattern passed as parameter.

• Automatically Extracting Instances of Code Change Patterns with AST Analysis (Martinez, M.; Duchien, L.; Monperrus, M.) IEEE International Conference on Software Maintenance (ICSM), pp.388-391, 2013, doi: 10.1109/ICSM.2013.54 bibtex

Mining Simple Changes (i.e., with exactly one change)

Extract all commits of repogit4testv0 that insert a binary operator AST node

java -classpath ./coming.jar fr.inria.coming.main.ComingMain -location  ./repogit4testv0/ -mode mineinstance -action INS -entitytype BinaryOperator   -output ./out

The argument -mode indicates the analyzer that Coming will use. The value -mode mineinstance means to detect instances of a change pattern (in the previous example, insert a binary operator AST node).

The argument -location indicates the location of the project to analyze. By default, Coming analyzes Git projects(as per -input), so the -location should be the path to the cloned project. Moreover, the argument branch allows to specify the Git branch to analyze (by default, it analyzes the master branch).

The argument -output is used to indicate the folder where Coming will write the results.

To know the values accepted by the arguments -action and -entitytype, please call ComingMain with the following arguments: -showactions and -showentities, resp. You can also find those values on this page.

Mining Complex Changes (i.e., Two or more changes)

Instead of passing the action type and entity type per command line (which defines simple pattern), we can pass to Coming complex change pattern specified in a XML file.

-mode mineinstance -pattern ./pattern_INS_IF_MOVE_ASSIG.xml

Here, -pattern must receive the location to an XML with the pattern specification.

This pattern is specified as follows:

<pattern>
	<entity id="1" type="Assignment">
		<parent parentId="2" distance="10" />
	</entity>
	<entity id="2" type="If" />

	<action entityId="2" type="INS" />
	<action entityId="1" type="MOV" />
</pattern>

Change Pattern Specification

Coming accepts Change Patterns specified in a XML files. As example the pattern Add If-Return:

<pattern>
	<entity id=``1" type=``Return">
		<parent parentId=``2" distance=``2" />
	</entity>
	<entity id=``2" type=``If" />
	<action entityId=``1" type=``INS" />
	<action entityId=``2" type=``INS" />
</pattern>

Specifies:

a) two entities (id 1 and 2), one representing a Return, the second one an If;

b) a parent relation between theifandtheReturnentities (with a max distance of 2 nodes); and

c) two actions of type INS (insert), one affecting the entity id 1 (i.e., the Return), the other one the entity id 2 (i.e., the if)

This pattern is able to match a changes such:

+  if ((n1 * n2) < MathUtils.SAFE_MIN) {
+           return ZERO;
+    }

That change is an instance of the pattern Add If-Return.

Roles of Entities

The pattern specification also allows to specify the role of an entity in its parent entity. Given the code:

   if (exception == null) {
-      l.connectionClosed(event);
+      l.connectionErrorOccurred(event);

...
+  if (realConnection != null)
-  if (realConnection == null)

The following pattern, that matches any changes inside an entity which parent is an IF, is able to detect two instances:

<pattern>
<entity id="1" type = "If"/>
<entity id="2" type = "*">
	<parent parentId="1" distance="10" />
</entity>
<action entityId ="2" type = "*" />
</pattern>

One of the instances is over the method invocation (which was an updated parameter), and the second one the operator inside the IF.

The role feature allows to specify a pattern that matches an element according to the role of the element in its parent.

For example, the following pattern matches an element (with ID 2) which role in parent is condition:

<pattern>

<entity id="1" type = "If"/>
<entity id="2" type = "*" role = "condition">
	<parent parentId="1" distance="10" />
</entity>

<action entityId ="2" type = "*" />

</pattern>

Thus, this patches will find one instance: the change inside the IF condition (update of binary operator) and it does not match with the other change (update of parameter).

However, the next pattern will uniquely match the second change: changes on an entity which parent has a role of Then block.

<pattern>
<entity id="1" type = "If"/>
<entity id="3" type = "Block" role = "Then">
	<parent parentId="1" distance="10" />
</entity>
<entity id="2" type = "*">
	<parent parentId="3" distance="10" />
</entity>
<action entityId ="2" type = "*" />
</pattern>

This pattern matches with the update of the method invocation's parameter (and not with the binary operator update)

The list of available Roles is presented on this page.

Mode Change Frequency

When running Coming in mode -mode diff the output is a file name `cha