git branch –create: Why Isn’t It Documented?

• ⚠️ git branch --create works despite not being officially documented in Git.
• 🛠️ Git’s internal parsing system sometimes allows unknown flags to execute without errors.
• 🚫 Relying on undocumented commands may cause future compatibility issues and lack of support.
• 🔄 Official alternatives like git branch, git checkout -b, and git switch -c are safer.
• 🔍 Similar quirks exist with other Git commands due to historical support for abbreviations.

Git Branch –Create: Why Isn't It Documented?

Git is one of the most widely used version control systems, but even experienced developers encounter surprises. One such mystery is the git branch --create command, which appears to work yet is missing from Git’s official documentation. Why does this command function, and what does it actually do? In this guide, we’ll break down how Git handles undocumented commands, whether you should rely on git branch --create, and the best practices for creating branches in Git.

What Does git branch --create Do?

At first glance, you might expect git branch --create new-branch to work the same way as git branch new-branch, which is the documented syntax for creating a new branch.

For instance, running:

git branch new-feature

creates a new branch called new-feature. Meanwhile, running:

git branch --create new-feature

also appears to do the same thing. However, if you check Git’s official documentation, there’s no mention of --create. This suggests that while the command may function, it is not officially supported. So what’s really happening here?

Why Isn’t git branch --create in the Git Documentation?

Git has an extensive set of officially documented commands (Git Documentation), yet --create is not one of them. This absence strongly indicates that --create is not a legitimate Git feature, but rather a quirk in Git's internal argument processing.

There are several possible reasons for this:

1. Parsing Flexibility – Git is designed to interpret a variety of command formats and may not strictly enforce all argument validations.
2. Ignored Unknown Flags – In some cases, Git may ignore unknown flags instead of blocking their execution.
3. Legacy or Unintended Behavior – It is possible that --create was at some point a valid option in past versions but was later removed from documentation while still being processed by Git's command parser.

Because --create is not listed as an official flag, relying on it could lead to unexpected issues, particularly in future Git updates.

How Git Interprets Unknown or Undocumented Commands

Git’s command-line parser allows for some flexibility in how it processes inputs. This can sometimes lead to undocumented commands functioning when they shouldn’t. Here’s why this happens:

1. Git Ignores Some Unknown Flags

Unlike strict CLI tools that reject unrecognized options immediately, Git occasionally ignores or misinterprets unknown flags, allowing the command to run.

2. Git Supports Historical Abbreviations

Git attempts to interpret partial or mistyped commands based on current features. Although --create is not explicitly listed, it may function due to some internal fallback logic.

3. Internal Argument Processing

Git follows specific patterns in how it processes command-line inputs. Some undocumented flags may be interpreted in meaningful ways even when they weren’t intentionally designed for public use.

In short, git branch --create likely works because of Git’s forgiving command parser rather than because it was ever intended to be a valid option.

The Correct Way to Create a Branch in Git

Because git branch --create isn’t a documented command, it is best to use officially supported methods when creating a new branch. Here are the proper ways to do so:

1. Using git branch (Recommended for Simple Creation)

This is the most basic command to create a new branch without switching to it:

git branch new-branch-name

2. Using git checkout -b (Older Alternative)

Prior to Git 2.23, the standard way to create and switch to a branch was:

git checkout -b new-branch-name

This command both creates the branch and moves you onto it.

3. Using git switch -c (Newer Alternative)

With the introduction of git switch, the more modern approach is:

git switch -c new-branch-name

This command achieves the same result as git checkout -b but is part of Git’s effort to make commands more intuitive.

4. Creating a Branch from a Specific Commit

If you need to create a branch from a specific commit (e.g., abc123), use:

git branch new-branch-name abc123

This creates a branch pointing to a specific commit.

These methods ensure that your workflow remains stable and supported in future Git versions.

Risks of Using git branch --create

Although git branch --create appears to function, relying on it can be risky. Here’s why:

• Future Compatibility Issues – There is no guarantee --create will work with future Git updates.
• Lack of Official Support – If an issue arises, finding documentation or community support may be difficult.
• Unexpected Behavior – Because --create is not an official flag, its reliability is not assured, and its behavior could change without notice.

For these reasons, sticking with officially recognized Git commands is the safer choice.

How Git Handles Abbreviated or Similar Commands

Git has a history of supporting shorthand commands and attempting to match partial inputs. This could explain why git branch --create works without being officially documented.

Examples include:

• Git Aliases – Many developers create shorthand commands like git co for git checkout via aliases.
• Partial Command Recognition – If a command is unique enough, Git can sometimes recognize and auto-complete it (e.g., git sta may suggest git status).
• Legacy Command Compatibility – Some older Git commands are still functional even if they have been replaced with newer versions.

This forgiving approach may be what allows git branch --create to execute instead of failing outright.

Other Undocumented Git Commands That Work

Beyond git branch --create, there are other undocumented but functional Git commands, such as:

• Deprecated or Hidden Flags – Some features may still be available but are undocumented because they are no longer recommended.
• Internal Debugging Flags – Some commands used by Git developers may still function in public releases.
• Legacy Commands – Older Git syntax may persist in some forms, even though newer alternatives are recommended.

While these undocumented commands can be useful for niche scenarios, they are not advisable for everyday use.

Final Thoughts

While git branch --create may appear to work, it is not an officially recognized Git command. It likely functions due to quirks in Git's argument handling rather than as a deliberate feature. To avoid potential issues, always use officially supported methods like git branch, git checkout -b, or git switch -c when creating branches. Understanding how Git processes commands can be useful, but relying on undocumented behaviors is not a best practice.

Citations

1. Chacon, S., & Straub, B. (2022). Pro Git (2nd ed.). Apress.
2. Loeliger, J., & McCullough, M. (2012). Version Control with Git: Powerful Tools and Techniques for Collaborative Software Development (2nd ed.). O'Reilly Media.
3. Git Documentation. (n.d.). Retrieved from https://git-scm.com/docs/git-branch