Basics

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

Illustration: a control panel with a big button and a row of small toggles; the robot flips one of them

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.

  • -v in node -v means version. In cp -v, "tell me what you're doing". In grep -v, "show lines that do not match".
  • -h is help in many programs. But in ls -lh and df -h it means "human-readable sizes", in KB and MB. And grep -h drops file names from the output.
  • -r in rm and cp means recursive, with all nested folders. In sort -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.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →