Raise visibility of this package?

[dgutov]

We have emacs-git-gutter for comparison, which is a younger project, and yet about twice as popular (according to GitHub's star count).

If there are easy ways to improve the situation (e.g. a rename, @purcell suggested "vc-gutter", but advised against this move in general). Or improving the README, to change the first impression. Then let's do it.

If the reasons are more difficult (e.g. strong Japanese following), then maybe not.

[purcell]

On reflection, I think you should rename. I've noticed a couple of times I wanted to call functions in this package with M-x, and simply couldn't remember the package name. So somehow diff and hl don't map closely in my brain to what it does. I think fringe or gutter needs to be in the name, and diff is okay, but I'm biased towards vc. So diff-gutter, diff-fringe, vc-gutter or vc-fringe would be my suggestions.

[dgutov]

Thanks for giving it some thought.

I wouldn't want to give an impression that only fringes are supported, so the -fringe options are out.

My only misgiving about vc-gutter is it's very close to the name of the other project, and it would not be great if people would mix them up from time to time. If no better ideas come up, though, guess I'll go ahead with it.

Speaking of a rename, any advice? If I rename the package and the repository at once, will the last version of diff-hl built by MELPA remain? I'd like to keep both the stars and the watchers on the new repository, so keeping both repositories at the same time might be tricky.

[purcell]

My only misgiving about vc-gutter is it's very close to the name of the other project, and it would not be great if people would mix them up from time to time. If no better ideas come up, though, guess I'll go ahead with it.

Yeah, I don't think that's really a problem, personally.

Speaking of a rename, any advice? If I rename the package and the repository at once, will the last version of diff-hl built by MELPA remain? I'd like to keep both the stars and the watchers on the new repository, so keeping both repositories at the same time might be tricky.

The last diff-hl will remain only if a recipe for diff-hl remains. There are ways to bridge the change-over, but ultimately the plan would have to be to remove the diff-hl package, so there might always be users who will update their package in 6 months time and find that package missing because its recipe was deleted. For that reason, I generally suggest being quite aggressive with renames, and embracing the breakage.

To do things more gradually, rename the repo via github, have both diff-hl.el and vc-gutter.el in it, and add a recipe for the latter. You can then make diff-hl.el print out a deprecation message. Once ready, be sure to tag the repo so that vc-gutter will be in MELPA Stable (since diff-hl will disappear), and then remove the diff-hl recipe and remove diff-hl.el from the repo. The vc-gutter recipe can then have :old-names (diff-hl) added, which at least will consolidate download statistics and cause the old package page to redirect to the new one. Maybe also add "(formerly diff-hl)" to the package description of vc-gutter.

[tarsius]

which is a younger project, and yet about twice as popular (according to GitHub's star count).

Which just means that it got a lot of attention sometime(s) along the way. Nothing a few blog posts about diff-hl couldn't fix. You should also add a detailed comparison to the documentation and not shy away from saying that your package is better.

The situation looks a little better when consulting Melpa statistics.

Package	Melpa Downloads	Last commit
diff-hl	156,279	20180201
git-gutter	103,147	20161105
git-gutter+	63,144	20151204

What really annoys me is the success of git-gutter+. Neither the maintainer of the fork nor the original seem to care about the confusion this causes. Most foo+ are extensions to foo so it is confusing that in this case it is a fork and the differences between the two versions are not properly documented. (Side note - I think git-gutter+ should be removed from Melpa.)

After trying to get this sorted out in 2014 (https://github.com/nonsequitur/git-gutter-plus/issues/11) I went with diff-hl instead.

I recommend against renaming. That's just going to be confusing and you don't actually know that more users will find this package after doing so. If you rename to vc-*, then you might actually get fewer new users because that implies that it has to do with the VC package, so why would a, say, Magit user install it?

[purcell]

The situation looks a little better when consulting Melpa statistics.

Yep, spacemacs and my config use diff-hl rather than git-gutter* by default.

[dgutov]

Prelude, I think, but not Spacemacs (which still uses git-gutter+ by default, probably because of the "stage hunk" command, which I have little intention of implementing).

[dgutov]

@tarsius

What really annoys me is the success of git-gutter+.

I wonder, does it even have any features these days that the parent doesn't?

you don't actually know that more users will find this package after doing so

They probably would, eventually. Looking around, the term "gutter" is pretty established these days across editors.

that implies that it has to do with the VC package, so why would a, say, Magit user install it?

Because "version control" is a general term, too? Not to mention that it uses VC. Not every Magit user is going to be aware of the built-in VC package anyway, and the most clever ones of those that do also set vc-handled-backends to nil, which will break this package. So some awareness of the relation to VC might not hurt either.

Anyway, how about diff-gutter, then? Or vcs-gutter.

[tarsius]

Anyway, how about diff-gutter, then?

I like that.

[seagle0128]

diff-hl is not popular and familiar name. I vote vc-gutter, but I am fine with diff-gutter as well.

[valignatev]

I'm up for renaming as well. This is a superior package with this kind of functionality for emacs, but its name is just undiscoverable.

[sten0]

Hi,

Quick reply to all previous posts: Shouldn't the short description provide the necessary discoverability? I don't think a rename would be beneficial, and that an updated short description would provide the necessary search keys.

I'm investigating packaging something that highlights changed lines for Debian, and the investigation was prompted by an RFP (request for packaging) for git-gutter-fringe (Bug #920383). Here's an updated table:

Package	Melpa Stable Downloads & percentile	Melpa Unstable Downloads & percentile	Last commit
diff-hl	2,698 & 91.44	203,934 & 96.83	20190223
git-gutter	7,927 & 96.34	144,980 & 95.70	20161105
git-gutter+	899 & 77.88	90,805 & 94.0.1	20151204
git-gutter-fringe	1,108 & 82.21	114,247 & 94.85	20170113
magit	37,352 & 99.90	731,573 & 99.93	20190508

Magit included as a control. When choosing between alternatives to package for Debian I take the delta between the stable and unstable percentile into account, but so far it's a toss up between git-gutter and diff-hl, with diff-hl edging ahead because it's a living project. @tarsius @dgutov interestingly, git-gutter+ has 16.12q, which led me to summarily eliminate it as an option. My hypothesis is that this delta increases when a project doesn't care about stability, either by not tagging release often enough, or by tagging unstable ones and losing users.

Four things that I believe would increase its discoverability/usage are:

1. Optimise the descriptions and README for key term search
   • I would take care that this is inherited by the Debian package description (eg: apt search key terms foo bar).
2. Possibly more visible integration with magit (magit-stage & unstage)
   • Do this to capture more new users, and more of the new generation...also magit can be seen as an established brand in the Emacs world.
   • Is this possible with the VC backend or would diff-hl need a toggle for this?
   • Add magit to the short description to make diff-hl more discoverable.
   • The Debian package can declare that diff-hl enhances magit, which means users who install magit are presented with a suggestion to also install diff-hl.
   • Maybe 2 can be solved in the README?
   • As a side effect, this, plus linking to magit website should boost search engine ranking.
3. If people blog about it or write articles about it and link to it, if Prelude/Spacemacs linked to this site, etc.
4. Presence in Debian and derivatives (Ubuntu et al)

Beyond that, a lot of people seem to want line numbers plus highlighting of changed lines. Personally I think it'd be cool if individual line numbers could be fontified/colourised for use with Emacs ≥26 display-line-numbers-mode..those other (dead?) projects will probably never add support for it, and from what I've read it's head and shoulders above linum or nlinum mode...and I read it doesn't use the margins or the fringe. Whoa, what? :-)

Cheers, Nicholas

[dgutov]

@sten0 I'm thankful for any suggestions how to improve the summary and the description, but diff-hl is not a plug-in for Magit, so it cannot be advertised as such (it works when Magit is not installed, and it will fail to work if the user disables the built-in VC subsystem, even when Magit would continue to work).

I haven't used Magit for a few years now personally, so for any features I would prefer implementations that don't rely on it. But if Magit-based commands are self-contained, people are welcome to propose some.

I'm totally fine with adding a link to Magit's website in the README if it helps. Note that the integration described in the relevant section is not automatic (people still have to add it to their init scripts). I could make it automatic, but we still have a seemingly-unresolved issue related to it (#65).

[dgutov]

@sten0 You haven't explained why you think a rename would be wrong, though. Losing search engine ranking? Github would create a redirect.

Regarding the coloring of line numbers, I'm not really sure it's possible (the new feature is implemented on the C level, and it's not very customizable). You're welcome to file a separate feature request in Emacs or here (I will pass it on then).

[sten0]

Hi @dgutov,

Thank you for maintaining diff-hl, and thank you for the quick reply!

On Thu, May 09, 2019 at 06:45:28AM -0700, Dmitry Gutov wrote:

@sten0 I'm thankful for any suggestions how to improve the summary and the description, but diff-hl is not a plug-in for Magit, so it cannot be advertised as such (it works when Magit is not installed, and it will fail to work if the user disables the built-in VC subsystem, even when Magit would continue to work).

Ok, I'll see what I can come up with :-) Of course, someone who works in search engine optimisation will have more useful insights. Please ping me if I seem to be taking too long.

I haven't used Magit for a few years now personally, so for any features I would prefer implementations that don't rely on it. But if Magit-based commands are self-contained, people are welcome to propose some.

I'm totally fine with adding a link to Magit's website in the README if it helps. Note that the integration described in the relevant section is not automatic (people still have to add it to their init scripts). I could make it automatic, but we still have a seemingly-unresolved issue related to it (#65).

I was thinking of something along the lines of some kind of opt-in defcustom that activates magit integration(and potential workarounds) and disables VC when a git repo is detected. If this was enabled but magit is not installed diff-hl would error when loading and fall back to VC. Alternatively I could just file a wishlist bug against magit, but that wouldn't help increase the userbase for diff-hl ;-) Of course I'm still willing to package diff-hl for Debian, even though I feel that VC and not Magit limits it to more niche appeal (I know one or two people who use VC and more than a dozen who use Magit).

@stribb, from #65

I tracked it down as far as (normal-mode) which runs after-change-major-mode-hook. The two hook functions which cause the infinite loop are magit-auto-revert-mode-enable-in-buffers and diff-hl-mode-enable-in-buffers.

Do you think a magit code path for diff-hl would be a good way to work around this? Eg: that diff-hl would take a different branch when using VC vs when using magit.

Sincerely, Nicholas

[dgutov]

I was thinking of something along the lines of some kind of opt-in defcustom that activates magit integration(and potential workarounds) and disables VC when a git repo is detected.

That's doesn't sound right. Magit integration works without disabling VC. Basically: Magit tells us when to update a buffer, but we still use VC to get the diff.

I know one or two people who use VC and more than a dozen who use Magit

I'm pretty sure there are a lot more of us. VC is installed by default, you don't need to configure anything to use it. So a lot of people use at least one or two features of it.

Do you think a magit code path for diff-hl would be a good way to work around this?

Whatever happens, already happens in a Magit code path. We could do something differently, but we'll need Magit people to tell us what. If the bug is still valid, of course.

[sten0]

Hi Dmitry,

Sorry for the delay, my mailbox and workload blew up and I'm only catching up now.

On Thu, May 09, 2019 at 06:49:18AM -0700, Dmitry Gutov wrote:

[1]@sten0 You haven't explained why you think a rename would be wrong, though. Losing search engine ranking? Github would create a redirect.

I don't think it's wrong so much as probably counterproductive to the stated objective... In addition to the reasons @tarsius presented over a year ago, here are a couple more:

At least 2/3 of the Emacs users I know are change averse, and an incidence where change is required becomes an opportunity to see what else is out there, reevaluate, and switch to something else; a rename that requires config changes risks losing users. Also, I think the 6months rename transition is counterproductive if the primary aim is to increase userbase, unless one has an aggressive rebranding campaign (at a minimum lots of people writing lots of articles)...and even then it doesn't work well. eg: Plasma Desktop. On the Emacs side, people are still confused about Counsel -> Ivy, and most new users ignore Counsel and only install Ivy.

Here is the Debian-side of things: I could add a "new-name PROVIDES diff-hl" as long as new-name will work with config files written for old-name, as long as a s/diff-hl/new-name/ for these config files isn't required, and it would be totally transparent to the user (eg: apt install elpa-diff-el would automatically map to elpa-new-name). Otherwise the diff-hl package just disappears in the next Debian version and users won't know about new-name. If compatibility is maintained for four or five years there probably wouldn't be an issue.

But for maximal user adoption, have you considered upstreaming diff-hl to Emacs proper? Then all users have it. As Magit is 3rd party it can just be ignored then, and there should be better opportunities for deeper integration (eg: the line-number-mode thing, focusing on VC, etc.)

Cheers, Nicholas

[sten0]

P.S. oh, and since upstreaming is an opportunity for a major epoch break you can rename it to whatever you want without maintaining backwards compatibility. Clean slate :-)

[sten0]

P.P.S.

Do you think a magit code path for diff-hl would be a good way to work around this?

Whatever happens, already happens in a Magit code path. We could do something differently, but we'll need Magit people to tell us what. If the bug is still valid, of course.

If diff-hl is upstreamed I'm sure the Magit people would modify Magit to provide the hint diff-hl. Bam, ~731,573 users ;-)

[dgutov]

Hi again, Nicholas!

an where change is required becomes an opportunity to see what else is out there

I see your point here, but I'm not really worried about a scenario like this. If somebody knows about this package, has tried it for a while, and then goes on to use something else, that's just fine with me. It's not the kind of package that's likely to invite lots of contributions anyway, and I'm not after high scores in download counts, or etc. A change being discussed here would be done solely for visibility among the people who hadn't heard about it yet.

Further, Plasma Desktop, which you compared against, is in a more difficult position where the competition is a lot more viable and well-maintained.

Speaking of upstreaming, though... that's a new idea. Nobody on the core asked for it. Not sure what the benefit would be for an average user, considering this package is already in GNU ELPA, and as such, installable right away.

[manuel-uberti]

I know this is old, but I am all in for diff-gutter. And I can write about this package on my blog too, if it could help spread the word somehow. Maybe after the rename, just to ensure I could point the readers to the right package.