Hardcoding `--ancestry-path` prevents generic `git rev-list` behavior

[bakhtos]

Is your feature request related to a problem? Please describe.
The current implementation of Conf.get_starting_commit() will always insert --ancestry-path to the git rev-list options if a from filter is given, which forces the returned commits to be direct descendants of the specified commit.

This makes it impossible to invoke generic git rev-list behavior such as git rev-list A..B or git rev-list A B ^C using PyDriller repository filters

Describe the solution you'd like
I propose to add filters descendants_of and ancestors_of which accept either a single commit or a list of commits, such that Repository(path, descendatns_of=['A', 'B'], ancestors_of['C', 'D']) results in the behavior git rev-list C D ^A ^B.

Additional context
I would say providing --ancestry-path as the only option is counterintuitive. E.g. I wanted to use pydriller to mine all commits that occurred between two releases R1 and R2 of a project and was puzzled as to why Repository(path, from="R1", to="R2") resulted in empty output, even though git rev-list R1..R2 provided commits. I wonder if some people used these filters without realising how they actually work in PyDriller.

[bakhtos]

I volunteer to make the PR if the feature is approved

[bakhtos]

I just noticed a related issue - ProcessMetric subclass only implements some of Repository filters. I think at the same time that class can be changed so that whatever can be passsed to Repository is accepted by ProcessMetric

[ishepard]

Hi @bakhtos ! Thanks for pointing this out.
As you may know, the difference between git rev-list A..Band git rev-list --ancestry-path=B ^Ais subtle, but still it's there.
I found myself using a lot more often the latter, so that's why I implemented that one.
For reference, when I want to specify a from and to commit, I only want the commits from commit from to commit to. I don't want commits that are reachable from the commit to as well.
E.g.,

	    D---E-------F
	   /     \       \
	  B---C---G---H---I---J
	 /                     \
	A-------K---------------L--M

If I specify from=D, to=M, I'm interested in:

		E-------F
		 \       \
		  G---H---I---J
			           \
			            L--M

Using D..M would get me:

	          E-------F
	            \       \
	         C---G---H---I---J
	                          \
	            K---------------L--M

As you can see, in this case we would get C, K as well, which I don't often want.

between two releases R1 and R2 of a project and was puzzled as to why Repository(path, from="R1", to="R2") resulted in empty output

Mmmm this is strange, not sure why it would happen! You can post the exact repo and command you used, maybe we can check why it's happening.

Said this, I'm not against implementing this. I think people might find it useful in certain scenarios.

Repository(path, descendatns_of=['A', 'B'], ancestors_of['C', 'D'])

I'd make it accept both a str and a list.

You also need to make sure it works with other filters, for example, the order in which commits are returned.

[bakhtos]

Hi @bakhtos ! Thanks for pointing this out. As you may know, the difference between git rev-list A..Band git rev-list --ancestry-path=B ^Ais subtle, but still it's there. I found myself using a lot more often the latter, so that's why I implemented that one. For reference, when I want to specify a from and to commit, I only want the commits from commit from to commit to. I don't want commits that are reachable from the commit to as well. E.g.,

	    D---E-------F
	   /     \       \
	  B---C---G---H---I---J
	 /                     \
	A-------K---------------L--M

If I specify from=D, to=M, I'm interested in:

		E-------F
		 \       \
		  G---H---I---J
			           \
			            L--M

Using D..M would get me:

	          E-------F
	            \       \
	         C---G---H---I---J
	                          \
	            K---------------L--M

As you can see, in this case we would get C, K as well, which I don't often want.

My point here is exactly that I thought from=D, to=M implements git rev-list D..M and so I would get the last pictured output. My colleague now made the same assumption in his data mining process, and I needed to explain to him that he is not getting all the commits he is expecting.

It is sound from semantic point of view that "from commit D" means "commits that are descendants of D", which is why I do not suggest to modify the current arguments but implement new ones.

Repository(path, descendatns_of=['A', 'B'], ancestors_of['C', 'D'])

I just realised that descendants_of would create identical confusion since git rev-list A..B returns not only descendants of A but other commits as well. What would be a more suitable keyword here? I can only think of add_ancestors_of=['A', 'B'], remove_ancestors_of=['C', 'D'] to result in git rev-list A B ^C ^D since this is what the command is tecnically doing - adding and subtracting sets of commits.

I'd make it accept both a str and a list.

Yes, I can make it so that if a str is passed, it is internally converted to a list of one element.

You also need to make sure it works with other filters, for example, the order in which commits are returned.

I assume the order can always be specified to git rev-list regardless of what commit range it considers, but I will double-check with documentation.