Replace example command line switch (option) abbreviations with their verbose equivalent.

[JohnLukeBentley]

Throughout the book there are command line examples. For example in Ch. Git Basics, sec. Recording Changes to The Repository, sub. sec. Committing Your Changes (p. 55 in the pdf) there is

$ git commit -m "Story 182: Fix benchmarks for speed"

I suggest, where a command line example includes an switch (option), the verbose version of a switch be used. As in ...

$ git commit --message "Story 182: Fix benchmarks for speed"

To a new user the verbose version of a switch makes it more apparent what the switch does. It's far more readable. As a new user becomes more familiar with the command it is easy, then, to learn the abbreviated version of a switch (e.g. through git commit -help; git commit -h; or git commit --help).

As far as I know almost all abbreviated switches have a verbose equivalent (but not the converse). There might be some exceptions. The help example I've given is one tricky exception (git commit -help; and git commit -h output to the command line. git commit --help outputs by opening a url in a browser).

[HonkingGoose]

Hi @ben, do you want a pull-request from me that replaces all short options with their verbose equivalent where possible?

Example:
$ git commit -m "Story 182: Fix benchmarks for speed would change to:
$ git commit --message "Story 182: Fix benchmarks for speed.

[ben]

I have an opinion on this, but I'm willing to be convinced I'm wrong.

The intent here should be to provide readers with a path to becoming proficient and effective with Git. To that end, we should use the short versions for the most part — I've never seen anyone type git commit --message 'names are hard' in a real-life scenario, they use -m every time. I think that anyone who's using the command-line interface regularly will be better-served by learning the short flags than the long ones.

Having said that, we don't want to leave first-time Git users out in the cold. We should definitely be describing what the flags do in prose the first time we use them. We definitely do that with -m the first time we use it. If any other flag is missing that treatment, I'd consider that a bug for sure.

[JohnLukeBentley]

@ben, your second paragraph has weight. I offer the following as a counter weight (whether it tips your scales is the issue and, of course, entirely a matter for you) ...

To take one example organisation Microsoft has, since the initial release of .Net, tended to promote a verbose naming convention as an improvement over the traditional propensity to be terse.

A contemporary Microsoft example of that convention is found in the Powershell docs (and powershell, rather than .Net, is perhaps a more relevant comparison to git since both are centered on a command line use) we have PowerShell 101 > Chapter 5 - Formatting, aliases, providers, comparison

Aliases can save you a few keystrokes and they're fine when you're typing commands into the console. They shouldn't be used in scripts or any code that you're saving or sharing with others. As mentioned earlier in this book, using full cmdlet and parameter names is self-documenting and easier to understand. [Emphasis added]

In pointing to what Microsoft does I don't wish to nakedly appeal to authority nor an appeal to popularity. Those naked appeals are fallacies. However, the first thing to note is that there is some convention here in favour of the verbose and conventions in-and-of-themselves, in this computer context, do count.

But more importantly is the reason for the convention conveyed in the quote: It's fine to use abbreviations at the console but sharing code is a different matter. Full parameter names are self-documenting in a way that abbreviations are not.

[JohnLukeBentley]

.... Some references to the .Net naming conventions: "General Naming Conventions" (as at 2008), by way of showing Microsoft's general promotion of the verbose over the terse.

✔️ DO favor readability over brevity.

The property name CanScrollHorizontally is better than ScrollableX (an obscure reference to the X-axis).

...

❌ DO NOT use abbreviations or contractions as part of identifier names.

For example, use GetWindow rather than GetWin.

❌ DO NOT use any acronyms that are not widely accepted, and even if they are, only when necessary.

[HonkingGoose]

Feedback on @ben's words:

The intent here should be to provide readers with a path to becoming proficient and effective with Git. To that end, we should use the short versions for the most part — I've never seen anyone type git commit --message 'names are hard' in a real-life scenario, they use -m every time. I think that anyone who's using the command-line interface regularly will be better-served by learning the short flags than the long ones.

I also use the shorthand flags most of the time. I agree proficient users of Git will likely use the shorthand flags. Learning the flags is a helpful thing to do, for sure.

Having said that, we don't want to leave first-time Git users out in the cold. We should definitely be describing what the flags do in prose the first time we use them.

Agree!

We definitely do that with -m the first time we use it. If any other flag is missing that treatment, I'd consider that a bug for sure.

I would be prepared to go trawl through the book to find out where those bugs are hiding. But this is a lot of work, and will take some thought and care.

---

I can see the value in @JohnLukeBentley points as well. Code is written once, but read many times. If you're sharing command line guides to co-workers, you better include the full flags for clarity... 😄

And for explanations, it's better to have the incantation be as clear as possible.

---

I will see how this pans out, @ben if you want me to do anything, just say so, and I'll go make pulls for the direction you want to take this.

[ben]

To take one example organisation Microsoft has, since the initial release of .Net, tended to promote a verbose naming convention as an improvement over the traditional propensity to be terse.

It's funny you mention this, because it was on my mind when I was writing my screed above. Microsoft's APIs have the flavor of "verbose but discoverable," and I think that's great if your'e designing an API. I first ran across this when trying to get used to Powershell back when it was new, and I could never get used to it — New-Item -Path 'C:\NewPowerShellFolder' -ItemType Directory just seemed like too much typing. Maybe that's the Vim user in me. 😁

Back to the point: having used WPF and CLR tech in the past, naming patterns like that are great for ramping up on a new API quickly. I definitely see the value in this approach. But we're not designing the Git API or UI here. Our job is to help people get better at the Git they have. I'd be in favor of a note somewhere which says "if you're writing a script that others will need to read, prefer the long versions of command-line flags; six months from now you'll thank us." But the path to more effective and efficient Git use is by knowing and recognizing the short flags for everyday use.

[HonkingGoose]

@ben, to verify before I start working. We'll keep the short-hand flags?

And you'll accept pull requests for the following:

• Describe what the command-line flags do in prose the first time we use them. If any other flag is missing that treatment, I'd consider that a bug for sure.

• Put a note somewhere which says "if you're writing a script that others will need to read, prefer the long versions of command-line flags; six months from now you'll thank us." Pending pull request at Add tip: use verbose CLI flags for shared scripts #1520.

[ben]

Confirmed, that's a good summary of my position here. Thanks!