What is a command-line flag — and why git commit -ma breaks but -am works

Here are two commands that look the same:
git commit -am "fix login"
git commit -ma "fix login"
The first one commits. The second fails with pathspec 'fix login' did not match any file(s). We checked. Swap two letters, and git suddenly hunts for a file named "fix login". The reason is how flags work. Five minutes from now you'll read any -xzvf without googling.
What a flag is, in plain words
A flag (also called an "option" or a "switch") is a setting for a command. The command says what to do; flags say how.
ls # show files
ls -l # show files as a list, with sizes and dates
ls -a # show hidden ones too
Flags come in two kinds:
- A toggle just turns a behavior on.
-a,--force,--draft. No value. - A flag with a value expects its value right after it.
-m "text",--title "Fix login",-n 5.
And two spellings. Short: one dash and one letter, -f. Long: two dashes and a word, --force. Often they're the same thing; the long one is just easier to read. Where flags sit in the overall "program → subcommand → flags → arguments" pattern, we covered in what is a CLI.
Glued flags: -rf and the -ma mystery
Short flags can be glued together. rm -rf folder is exactly rm -r -f folder. And ls -la is ls -l -a. So tar -xzvf isn't one mysterious word — it's four flags: x, z, v, f.
Now the puzzle from the top. In git commit -am "fix login", two flags are glued:
-a— a toggle: "stage all modified files";-m— a flag with a value: "here's the commit message".
-m takes as its value whatever comes after it. In -am, nothing follows the m, so the message is the next word, "fix login". All good.
In -ma, the letter a sits right after the m. So git decides, honestly: the commit message is "a". And "fix login" is left over as an extra word, which git assumes is a file name. Hence the error.
A rule for life: in a glued group, put the flag that takes a value last. That's how -am, tar -czf archive.tar.gz, and ssh-keygen -t ed25519 work.
One letter, different meanings
The second trap. Flags have no shared dictionary. Each program decides what its letters mean.
-vinnode -vmeans version. Incp -v, "tell me what you're doing". Ingrep -v, "show lines that do not match".-his help in many programs. But inls -lhanddf -hit means "human-readable sizes", in KB and MB. Andgrep -hdrops file names from the output.-rinrmandcpmeans recursive, with all nested folders. Insort -r, it means reverse order.
So don't carry a flag from one command to another from memory. It's a common mistake for people and for AI: a model remembers a flag from a similar program or an old version. If a flag is unfamiliar, check it in ten seconds — the guide on how to read command help shows how.
The double dash -- and the lone dash -
Two marks that look like typos but are very useful.
-- means "no more flags". Everything after it is a plain argument, even if it starts with a dash. Say a file named -rf appeared by accident. rm -rf won't delete it: it reads that as flags. This works:
rm -- -rf
We checked: that file was removed, the rest stayed. The same -- shows up in git checkout -- file and in npm run dev -- --port 4000. In the second case npm leaves everything after -- alone and passes it to your script.
A lone - often means "read from input, not a file". For example, cat - waits for text from the keyboard or a pipe. We explained that input in what is stdin.
FAQ
--port=4000 or --port 4000 — any difference?
For most programs, no: both are understood the same way. The = form is safer when the value starts with a dash or when a script builds the command.
Does flag order matter?
Usually not: ls -a -l and ls -l -a are the same. It matters inside glued groups (value-taking flag last) and in commands with subcommands: in git, flags before commit and after commit apply to different things.
Why does AI sometimes give me a flag that doesn't exist?
The model may remember a flag from another program or an older version of this one. If the command complains about an unknown option, paste your version's --help output to the AI and ask it to rewrite the command from that.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





