Git Flag Syntax: why do some flags have -one dash and some have --two?

Question

I am learning Git and have been unable to find any explanation of the flag syntax.

I'm not referring to the "bare double dashes"

--

which, as we know, indicate that what follows is not an option. I'm referring to various actual flags which sometimes have one dash, and sometimes have two.

git log -2 -p -U1 --graph

What is the difference between a flag with one dash and two dashes? What does the double dash indicate?

For example, the following two flags are identical, (according to this):

-q
--quiet

Why the different number of dashes? What if I put the wrong number?

Bandolier

Or what about options that require no dashes (ie, git stash list)? – Halimeda

Answer 1

My understanding is that git follows the 'standard' Linux convention for flags. That is:

• one dash for 'short' flags: generally one character flags, but sometimes flags with a single character, then further characters which represent a parameter to the flag (e.g. git log -SFoo, in which Foo is a parameter to the -S flag). These flags may or may not be abbreviated forms of other, longer flags.
• Two dashes for 'long' flags: multi-character flags which are usually an English word. If these flags receive parameters, it is separated from the flag by an = sign (e.g. git log --author=Peter).

This is the 'why': it is a convention which is embedded in the Linux world. Git comes from this world, so it follows the convention. The 'two dashes for a long flag, one for a short flag' rule should guide you as to how many dashes to use for a flag.

As for why there are duplicate short and long flags, such as --quiet and -q, it's just to provide the option of either mnemonic convenience or terseness. --quiet is easier to remember, but -q is quicker to type and mentally parse if you're used to it. For instance, I type git commit -m "...blah" so frequently it would get on my nerves if I had to double the length of my command every time by entering git commit --message='...blah'.

I haven't come across any git flags which behave differently given two dashes and one dash, so generally if you enter two dashes for a one-dash flag or vice versa, nothing irreparably bad will happen, git will just complain about your flags and do nothing.

Of course, git has a vast number of commands, each with a vast number of flags, so it is possible that there are exceptions to all these rules. They should generally hold though.

Preussen

The long flags are also often preferred in scripts, since someone reading a script instantly has a good idea of what --quiet does, but something like -q will likely need to be looked up to understand what it does. – Monadelphous

Traditionally short flags can be bundled; for example ls -ltr is equivalent to ls -l -t -r. But git doesn't seem to support that. – Cabral

@KeithThompson Some git commands do support bundling, such as git grep. I don't know the rationale for supporting or not supporting it for a given command, though. – Preussen

@Peter: I suspect there is no rationale. – Cabral