git stash: add clear

[solygen]

No description provided.

[CLAassistant]

All committers have signed the CLA.

[mention-bot]

@solygen, thanks for your PR! By analyzing the history of the files in this pull request, we identified @ericbn, @kalebo and @rubenvereecken to be potential reviewers.

[waldyrious]

Thanks, I didn't know about that one. But unfortunately the page is already longer than our recommendations (5-6 examples), and this change bumps it even further beyond that. I've been considering for a long time that we should perhaps consider raising the limit to, say, 10 commands, and make that a hard limit (no trespassing!). What do you think, maintainers? @tldr-pages/content

[agnivade]

10 is too much. My suggestion is to try to keep it to 6, with 7 being the hard limit in case of rare exceptions.

In this case, I think git stash drop can be easily used to build up git stash clear.

[waldyrious]

We've hit this limit several times already, which is why I suggested raising it. I'm afraid it may be doing more harm than good, especially for commands that cannot be properly summarized in a handful of examples.

[ericbn]

@agnivade, @waldyrious, what if, instead of establishing a limit of examples, we start thinking about a limit of terminal space that we want to occupy?

[waldyrious]

@ericbn that will vary quite a bit depending on the user environment. It's more important, IMO, to discuss this in terms of cognitive load (number of examples) rather than the particular formatting style. This is especially relevant since each client is free to render the output however they prefer, e.g. by making it more compact or more spaced-out.

[agnivade]

We've hit this limit several times already,

Yes, that's why I think we should not exceed the limit any more.

especially for commands that cannot be properly summarized in a handful of examples.

My viewpoint is that we should take 6 or 7 most important examples and leave out the rest. People will keep adding new examples. We need to decide if its worth it.

Slightly unrelated quote, but couldn't resist it 😝

Perfection is achieved, not when there is nothing more to add, but nothing left to take away.

--Antoine de Saint-Exupery

[waldyrious]

Yes, that's why I think we should not exceed the limit any more.

When I said "We've hit this limit several times already", I didn't mean that we've trespassed it several times (although that's also true), but that we've kept commands out, multiple times, for the sake of respecting our fairly arbitrary limit.

Is a way, it's like hitting a wall and bouncing back. If that is happening too often, it may signal that the wall is set too close.

The main question here is: is keeping out the commands that don't fit (and thus retaining a shorter tldr page) more valuable than providing the examples they'd introduce, especially if they aren't closely related to the ones already present in the page? (The latter test fails for this particular PR, as you've said.)

I'm not sure 5-7 is that much better than 10 to justify depriving users of the additional usefulness -- but maybe we could compromise and use a round number in base 2 --8, in this case-- rather than one in base 10? That would cap the page size to 29 lines, assuming a 2-line description. It's not too long IMO, and would allow decoupling some examples that demonstrate two options at once to workaround this limit, rather than because they make more sense together.

[agnivade]

I'm okay with 8. :)

[waldyrious]

I'm okay with 8. :)

Awesome! @Ostera, @tldr-pages/content any further comments? I'd say if nobody objects for a couple days, we should amend CONTRIBUTING.md accordingly and accept this PR.

[agnivade]

@waldyrious - I think the discussion digressed us from commenting on the PR 😆 Given that we agree on 8. 👍 from me.

[waldyrious]

@agnivade I'll amend CONTRIBUTING.md before accepting this, for chronological coherence :P

[waldyrious]

Max number of entries expanded (made explicit, really) to 8 in f0d4c16. This PR can now be meged.

Thanks, @solygen, and sorry for the delay! 😇