CommitFilter ahead/behind are confusing... #1069
Conversation
Thanks for this very detailed explanation that makes a lot of sense. Although I'm not sold on Besides, after a quick look, I'd say the xml doc would also deserve some love as "starting points" means barely anything. |
|
How about |
|
I think the desired naming depends on your mental model. Git CLI uses a time based model (ex LG2# is using a graph search (descendant to ancestor) approach. Both are legitimate. Our naming is poor. Better names and I think we're OK. So, if we're sticking with the "graph search" concept, then |
|
Agree that If not |
|
|
|
I'd go with |
|
I suggested |
|
|
|
From and To are a popular pair of bookend words as well. |
|
I know English isn't my native language, but I've got the impression that How about |
|
|
|
Let me ask this: is the search directional? If it is, |
|
Tagged as |
|
The git-log doc states Considering this above, I'd agree that using |
|
Agreed. However in both of the cases above the parameter type is a date and not a commitish. How about we just use |
Honestly, I don't know. If we can't decide which one is better than the other, maybe it's a sign that those may not be much clearer than the current implementation. @carlosmn As you're our own "Name Whisperer", we'd really like some of your magic. |
|
Got it: Older and Newer. |
|
What does older and newer mean in a directed graph when date is just meta data and arbitrary? |
Yes, a
Ancestors are conceptually older than their descendants? I don't think it's a particularly good option, but it seems a little less ambiguous? It's probably safest to align with the language from the git revisions docs:
|
|
Given the constraints of |
|
Per Wikipedia we should be using |
|
I kind of like Regarding the other one, I'd like something that also reflects the fact that the designated commit(s) won't be returned (as they will be hidden along with their ancestors). |
|
👍 to avoiding time concepts with the parameter names |
|
Given we're going back and forth on naming these parameters and not getting far, and the general confusion about traversing graphs appears to be a theme, would it be worth having some good samples to use as a reference for discussion? A couple of benefits for this:
As a starting point, we could open a PR with a test repository containing a couple of example graphs (for example, the "diamond" scenario) to kick things along. |
|
How about plain |
|
@nulltoken Naming this damn API is harder than authoring it. Maybe we should just stick to the Git docs and call the values |
|
|
|
I like where @dahlbyk is going with this, but how about |
|
Regardless of the names we choose, I do think we're going to need very good documentation both in the .md as well as in the inline documentation comments. Finally a use for the |
How does ASCII art renders in such tags? |
Why not. @DavidJanson There are a ton of proposal above. Anyone that would feel like a better fit from a user's perspective? |
Honestly do not know, but without a good example comparing it to how git.exe operates, confusion/frustration like what @DavidJanson reported will continue. |
|
I was hopping to include some commit graph... |
|
You mean like the examples on the Git SCM site? And by the way the parameter terms for We should look at the terms they have and how they use them, many of those terms have meaning in the context of a Git graph and should be excluded from this conversation. Example: |
🐰 🐇 |
|
How about |
I'll just blame this on a nature-friendly keyboard layout. 😉
|
Oh, I like that. |
|
Include/Except seems maybe more discoverable? Walk may be the preferred term for a graph, but commit logs tend to be characterized as lists. |
I've personally never thought of them that way. I suppose we return them as a linear collection, but that's arbitrary (and slightly incorrect behavior encourages by the paradigms of the language in use). We're basically doing a "leaf to trunk" read back of a graph, with "leaf" being defined as the starting where we start walking and "trunk" being the end-point where we stop. @nulltoken's suggestion of |
|
@dahlbyk That may be a language issue, but I read |
But that's exactly what it is - a list of commits to leave out of the result. Could expand to
|
|
@dahlbyk I wasn't very clear.
|
Unless anyone strongly opposes, I'm going to shortly issue a PR with this proposal |
👍 |
👍 |
CommitFilter ahead/behind are confusing...
I’m using libgit2sharp to emulate this: “git log HEAD~2..HEAD”
This fails to find any commits:
This successfully finds both commits:
This makes sense only if you consider that internally, the walk is starting at HEAD and going backwards to HEAD
2. However, this is grammatically confusing because I'm really intending to get the commits starting at HEAD and ending at HEAD2. The fact that it walks backwards feels like an implementation detail; it really isn't what I'm trying to express. This is especially true when compared to the git command line which grammatically reads left (start) to right (end).You can see the very natural confusion in the sample:
https://github.com/libgit2/libgit2sharp/wiki/git-log
Note that this is only a problem because the choice in words in the structure don't meet the natural expectation. Humans (even developers) just don't naturally think backwards; time (and relationships) moves "Since" something in the past "Until" something in the future.
It's too late to change the behavior but two new properties that are effectively the same (aliases) could be added. IMHO, going with the Git "revrange" documentation of "Rev1" and "Rev2" is best since it doesn't rely on natural grammatical terms which might have naturally different implication.
Dave