Open-source project
k88hudson/git-flight-rules avatar
k88hudson/git-flight-rules

git-flight-rules: A Scenario-Based Git Rescue Manual

Flight rules for git

42,570 stars3,167 forksUnknownCC-BY-SA-4.0

At a glance

What is it?
git-flight-rules is a community-maintained collection of step-by-step solutions for common Git emergencies, organized by situation rather than by command. It is a reference for developers who know Git basics but need quick, reliable fixes when things go wrong.
Who is it for?
Adopt git-flight-rules if you are a developer or team lead who frequently hits Git problems and wants a quick, scenario-based reference without reading long manuals. It is also useful for onboarding new developers who need to recover from common mistakes.
Can I use it commercially?
Yes, with credit. CC-BY-SA-4.0 allows commercial use as long as you credit the authors and indicate what you changed. It is written for creative content, so check how it applies to any code.
Is it still maintained?
Yes. The repository last received commits 17 days ago.
What is it written in?
GitHub does not report a main language for this repository.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • k88hudson/git-flight-rules42,570 ★ · -25
Star history
Repository2026-08-182026-11-15
k88hudson/git-flight-rules42.6k42.6k

-25 Stars in the last 89 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What Problem Does This Solve?

Git is powerful but unforgiving. When you accidentally reset, commit to the wrong branch, or push sensitive data, the standard `git --help` output does not tell you what to do next. git-flight-rules fills that gap. It is a collection of short, scenario-based procedures, each starting with a user intent like 'I want to discard my local uncommitted changes' or 'I accidentally did a hard reset, and I want my changes back.' The target audience is programmers who already know Git basics but need a quick reference when something goes wrong. It is not a tutorial; it is a manual for recovery. The README explicitly compares it to NASA's flight rules, which are detailed, scenario-specific standard operating procedures. That framing is accurate: each rule gives a step-by-step solution and explains why it works, which is more useful than a bare command list.

How It Is Organized: Intent Over Command

The document is organized by the user's goal, not by the Git command. The table of contents shows sections like 'Repositories', 'Editing Commits', 'Staging', 'Discarding changes', and 'Branches'. Under each section, entries are phrased as problems: 'I wrote the wrong thing in a commit message', 'I want to remove a file from the previous commit', 'I want to unstage a specific staged file'. This structure is the core design choice. Instead of asking 'what does `git reset` do?', you ask 'I want to delete or remove my last commit' and find the exact command sequence. The README also explains the prompt convention: a customized bash prompt shows the current branch in parentheses, and a `*` next to the branch name indicates staged changes. This makes the examples easier to follow because you can see the state before and after each command. The organization is practical, but it means the document is not a linear read; it is a lookup table.

Getting Started: No Installation, Just Read

There is no installation step. git-flight-rules is a documentation repository, not a tool. To use it, you clone the repository or read the README on GitHub. The README is available in multiple languages, including English, Spanish, Russian, Chinese, Korean, Vietnamese, French, and Japanese, which is useful for international teams. The commands in the examples are designed to work with Git version 2.13.0 or later, as stated in the 'Conventions' section. To get the most out of the guide, you should have Git 2.13.0 or newer installed. If you have an older version, some commands may not work as shown. The document itself recommends checking the official Git website to update your local version. Since it is a static document, there is no build process or configuration. You simply open the README and search for your scenario.

What the Rules Cover: From Amends to Sensitive Data

The table of contents reveals a wide range of scenarios. In the 'Editing Commits' section, you find solutions for fixing commit messages, changing the author name and email, removing a file from the previous commit, and deleting the last commit. The 'Staging' section covers partial staging, breaking staged edits into separate commits, and swapping staged and unstaged changes. The 'Discarding changes' section handles reverting local modifications, and discarding untracked files. There is also a section on removing large or sensitive files from history, with a recommended technique using the third-party tool BFG and a built-in technique using `git filter-branch`. This is one of the most valuable parts because it addresses a problem that many developers face but rarely know how to solve correctly. The inclusion of both a third-party and a built-in approach shows a practical mindset: use the easier tool when possible, but know the fallback.

Limitations: Not a Tutorial, Not Always Current

The biggest limitation is that this is a static document. It is not a tool that checks your repository state or gives interactive advice. You must match your situation to the right rule, and if your scenario is not listed, you are on your own. The README states that commands should work for at least Git 2.13.0, but Git has evolved since then. Some commands may have changed or been deprecated. The repository is not archived, its last push was on 2026-10-29, and it has no GitHub releases, which is normal for a documentation repository. Users should verify commands against their Git version and the official documentation. Another limitation is that the guide assumes a certain level of Git knowledge. A complete beginner will need a separate tutorial.

Alternatives: Official Docs and Interactive Tools

The most direct alternative is the official Git documentation, which includes a reference manual and a user's guide. The official docs are authoritative and always up to date, but they are organized by command, not by scenario. If you do not know which command to look up, you can spend a lot of time searching. Another alternative is interactive tools like `tig` or `gitk` that visualize the commit graph, but they do not give step-by-step recovery procedures. For specific problems like undoing a hard reset, `git reflog` is the underlying mechanism, and the official docs explain it. The difference in approach matters: git-flight-rules is a curated list of common mistakes and their fixes, while official docs are a comprehensive reference. If you need to recover from a rare or complex situation, the official docs will be more reliable. If you need a quick answer for a common mistake, git-flight-rules is faster.

Maintenance and License: What You Need to Know

The repository is licensed under CC-BY-SA-4.0, which means you can share and adapt the content as long as you give appropriate credit and distribute any adaptations under the same license. This is a documentation license, not a software license, so it is important to understand the implications if you plan to fork the repository or incorporate parts into your own documentation. The project is not archived and was last pushed on 2026-10-29, though Git changes over time, so it is worth checking commands against your version. For example, the built-in technique for rewriting history uses `git filter-branch`, which the official Git documentation now warns against in favor of `git filter-repo`. The guide recommends BFG as a third-party tool. Users should be aware that some advice may be outdated. The multi-language translations are a plus, but they may also lag behind the English version.

Editorial conclusion

Adopt git-flight-rules if you are a developer or team lead who frequently hits Git problems and wants a quick, scenario-based reference without reading long manuals. It is also useful for onboarding new developers who need to recover from common mistakes. Do not use it as a primary Git tutorial; it assumes you already know basic commands and focuses only on recovery. Before relying on it, verify that the commands match your Git version, since the document targets at least 2.13.0. Also, check the license (CC-BY-SA-4.0) if you plan to reuse or modify the content. Git changes over time, so cross-check critical commands against the official Git documentation.

Frequently asked questions

What are 12 common commands in Git?

It is organized as an index of situations, grouped into Repositories, Editing Commits, Staging, Discarding changes, and Branches, with entries phrased as the mistake you made rather than as the command to run, and its commands are written to work for at least git version 2.13.0.

What are the 5 steps of Git?

The contents are grouped by problem area instead, with sections for Repositories, Editing Commits, Staging, Discarding changes, and Branches, and the order in which you need them depends entirely on which mistake you are trying to undo.

Is Git checkout obsolete?

The conventions section states that all commands should work for at least git version 2.13.0, and it points readers at the git website to update a local install.

What does Git push '-u do?

In Git, -u (--set-upstream) makes the local branch track the remote branch. Related entries in the index include discarding local commits so your branch matches the one on a server, and a separate entry for the case where you pushed an amended commit to a remote and got an error message.

Official sources

  1. Official README
  2. Project repository
  3. README
  4. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/k88hudson-git-flight-rules.svg)](https://hysenlabs.com/projects/k88hudson-git-flight-rules)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/k88hudson-git-flight-rules.svg)](https://hysenlabs.com/projects/k88hudson-git-flight-rules)

Was this useful?