idea: difference reporting when running `tldr --update`

[bl-ue]

As a tldr maintainer (and user), I would like to be able to see the differences between my old state my new state of the pages when I update the pages via tldr --update. Currently, when I run tldr --update, it always shows the same output, regardless of whether or not any pages were created/updates.

I'm thinking something like this (pretty sketchy at the moment):

$ tldr -u
✔ Updating...
✔ Creating index...
pages/common/abc.md added
pages.fr/linux/def.md modified
pages/common/R.md deleted
pages/common/r.md added

I'll work on this if we decide upon it.

[owenvoke]

Do you directly modify the ~/.tldr/cache directory as a Git repo for your pages? 🤔 I've always just used tldr --render {{page.md}}

---

Edit: Oh, I see. It's pages that have been modified (i.e. updated in the cache), rather than ones that you have modified. 🤦🏻

I wonder if it'd be worth having this only when a flag is applied, e.g. --verbose/-v, as this may be quite a large output when people first get the cache, or haven't updated their cache for months, etc.

[bl-ue]

I was thinking the same thing. 👍🏻

[vladimyr]

I wonder if it'd be worth having this only when a flag is applied, e.g. --verbose/-v, as this may be quite a large output when people first get the cache, or haven't updated their cache for months, etc.

This exactly! In its default form, it shouldn't report more than 3 lines containing the number of added, deleted, and updated pages.

However, it is quite unlikely that this will ever get implemented. Not being backed by git is sort of tldr's original sin. It currently updates the cache by simply overwriting stuff and in order to show the suggested output, you would need to calculate diff on-the-fly on the user's machine. That would, in turn, drastically slow down the whole update process which is already unbearably slow due to index building. ⚠️

[bl-ue]

Actually, I discovered something that made be not sure that we could even use Git. See here. cc @waldyrious—is this correct?

[vladimyr]

@bl-ue I'm not advocating switching to git, that ship has sailed away a long time ago. That was just an observation.

OTOH specification defines a contract. And there was no technical dealbreaker, back then, nor now, that prevented creating one based on git workflow. It is simply a choice, one made long ago together with all pros and cons originating from it.

[waldyrious]

@bl-ue I don't recall a decision (or a technical restriction) that determines git to be inadequate for clients' cache. The client spec was fleshed out in issue tldr-pages/tldr#1065 and PR tldr-pages/tldr#2706, and @sbrl might be the right person to ask, as he drafted the initial spec.

That said, I'd point out some comments from tldr-pages/tldr#1065, such as this one by me:

Personally I'd prefer if all clients fetched from the git repo, but it's understandable that git can't be expected to be always available.

...this one by @pepa65:

The most important consideration when using Github for pages retrieval is availability, because of Github's download rate limitations on certain locations but not others. It seems the assets directory on http://tldr-pages.github.io is a good place.

...and this one by @MasterOdin:

I'd also suggest putting in a MUST on how the cache is gotten (e.g. python client currently gets one page at a time, node gets the zip, all clients should do the latter).

I didn't follow the discussion in tldr-pages/tldr#2706, so there may have been relevant comments there as well.

There's also some discussion on using git in tldr-pages/tldr#527, such as this comment by @sitaramc:

if you are going to cache stuff anyway, why not just use a local clone? I am sure 'git fetch' is a lot more efficient, especially if you're going to tldr many different commands

...and this one from @igorshubovych:

I think relying on Git is not for everybody. It is very inconvenient for contributors.

There are several situations, where git pull --rebase can be dangerous:

• you are not on the master branch
• you are in the middle of some work
• you are on your own fork

There's a tangentially related issue, tldr-pages/tldr#343, which suggest switching from .zip to .tar.gz; there, @agnivade commented:

Closing it as discussed on #9. TLDR: Clients should prefer git over manually downloading .zip archives.

Interestingly, that comment refers to the extensive discussion from issue #9 in this very repo, which covered the topic of relying on git for the cache. Turns out it wasn't implemented, though?

In any case, I'd recommend reading the threads above to give these quoted comments proper context; perhaps the authors of the comments will have relevant input here as well. it would definitely be nice to reach (or resurface) a clear decision on this topic.

[waldyrious]

By the way, while re-reading tldr-pages/tldr#1065, I found this comment I wrote back in 2016, suggesting exactly what this issue is proposing! 😄

I'd add that --update should list the new / changed commands

I actually really like Homebrew's default behavior of listing all added, updated and deleted formulas when doing brew update. I don't think we should hide those updates behind a --verbose flag — IMO it's a great way to highlight the amount of activity that happens in the project, and I suspect it might encourage users to engage as contributors.

[pepa65]

While doing an update, the old cache directory could be (temporarily) copied and then the output of diff -qr between both trees could be displayed. But for normal users this should not really be of interest.

[vladimyr]

the output of diff -qr between both trees could be displayed.

If there is a diff available on the user's machine.

[pepa65]

I can't imagine someone having a use for tldr on a machine that doesn't have diff..!