Flight rules for Git
🌍
English ∙ Español ∙ Русский ∙ 繁體中文 ∙ 简体中文 ∙ 한국어 ∙ Tiếng Việt ∙ Français ∙ 日本語
What are "flight rules"?
A guide for astronauts (now, programmers using Git) about what to do when things go wrong.
Flight Rules are the hard-earned body of knowledge recorded in manuals that list, step-by-step, what to do if X occurs, and why. Essentially, they are extremely detailed, scenario-specific standard operating procedures. [...]
NASA has been capturing our missteps, disasters and solutions since the early 1960s, when Mercury-era ground teams first started gathering "lessons learned" into a compendium that now lists thousands of problematic situations, from engine failure to busted hatch handles to computer glitches, and their solutions.
— Chris Hadfield, An Astronaut's Guide to Life on Earth.
Conventions for this document
For clarity's sake all examples in this document use a customized bash prompt in order to indicate the current branch and whether or not there are staged changes. The branch is enclosed in parentheses, and a * next to the branch name indicates staged changes.
All commands should work for at least git version 2.13.0. See the git website to update your local git version.
Table of Contents generated with DocToc
Repositories
I want to start a local repository
To initialize an existing directory as a Git repository:
(my-folder) $ git init
I want to clone a remote repository
To clone (copy) a remote repository, copy the URL for the repository, and run:
$ git clone [url]
This will save it to a folder named the same as the remote repository's. Make sure you have a connection to the remote server you are cloning from (for most purposes this means making sure you are connected to the internet).
To clone it into a folder with a different name than the default repository name:
$ git clone [url] name-of-new-folder
I set the wrong remote repository
There are a few possible problems here:
If you cloned the wrong repository, simply delete the directory created after running git clone and clone the correct repository.
If you set the wrong repository as the origin of an existing local repository, change the URL of your origin by running:
$ git remote set-url origin [url of the actual repo]
For more, see this StackOverflow topic.
I want to add code to someone else's repository
Git doesn't allow you to add code to someone else's repository without access rights. Neither does GitHub, which is not the same as Git, but rather a hosted service for Git repositories. However, you can suggest code using patches, or, on GitHub, forks and pull requests.
First, a bit about forking. A fork is a copy of a repository. It is not a git operation, but is a common action on GitHub, Bitbucket, GitLab — or anywhere people host Git repositories. You can fork a repository through the hosted UI.
Suggesting code via pull requests
After you've forked a repository, you normally need to clone the repository to your machine. You can do some small edits on GitHub, for instance, without cloning, but this isn't a github-flight-rules list, so let's go with how to do this locally.
# if you are using ssh
$ git clone [email protected]:k88hudson/git-flight-rules.git
# if you are using https
$ git clone https://github.com/k88hudson/git-flight-rules.git
If you cd into the resulting directory, and type git remote, you'll see a list of the remotes. Normally there will be one remote - origin - which will point to k88hudson/git-flight-rules. In this case, we also want a remote that will point to your fork.
First, to follow a Git convention, we normally use the remote name origin for your own repository and upstream for whatever you've forked. So, rename the origin remote to upstream
$ git remote rename origin upstream
You can also do this using git remote set-url, but it takes longer and is more steps.
Then, set up a new remote that points to your project.
$ git remote add origin [email protected]:YourName/git-flight-rules.git
Note that now you have two remotes.
origin references your own repository.upstream references the original one.
From origin, you can read and write. From upstream, you can only read.
When you've finished making whatever changes you like, push your changes (normally in a branch) to the remote named origin. If you're on a branch, you could use --set-upstream to avoid specifying the remote tracking branch on every future push using this branch. For instance:
$ (feature/my-feature) git push --set-upstream origin feature/my-feature
There is no way to suggest a pull request using the CLI using Git (although there are tools, like hub, which will do this for you). So, if you're ready to make a pull request, go to your GitHub (or another Git host) and create a new pull request. Note that your host automatically links the original and forked repositories.
After all of this, do not forget to respond to any code review feedback.
Suggesting code via patches
Another approach to suggesting code changes that doesn't rely on third party sites such as Github is to use git format-patch.
format-patch creates a .patch file for one or more commits. This file is essentially a list of changes that looks similar to the commit diffs you can view on Github.
A patch can be viewed and even edited by the recipient and applied using git am.
For example, to create a patch based on the previous commit you would run git format-patch HEAD^ which would create a .patch file called something like 0001-My-Commit-Message.patch.
To apply this patch file to your repository you would run git am ./0001-My-Commit-Message.patch.
Patches can also be sent via email using the git send-email command. For information on usage and configuration see: https://git-send-email.io
I need to update my fork with latest updates from the original repository
After a while, the upstream repository may have been updated, and these updates need to be pulled into your origin repo. Remember that like you, other people are contributing too. Suppose that you are in your own feature branch and you need to update it with the original repository updates.
You probably have set up a remote that points to the original project. If not, do this now. Generally we use upstream as a remote name:
$ (main) git remote add upstream <link-to-original-repository>
# $ (main) git remote add upstream [email protected]:k88hudson/git-flight-rules.git
Now you can fetch from upstream and get the latest updates.
$ (main) git fetch upstream
$ (main) git merge upstream/main
# or using a single command
$ (main) git pull upstream main
Editing Commits
What did I just commit?
Let's say that you just blindly committed changes with git commit -a and you're not sure what the actual content of the commit you just made was. You can show the latest commit on your current HEAD with:
(main)$ git show
Or
$ git log -n1 -p
If you want to see a file at a specific commit, you can also do this (where <commitid> is the commit you're interested in):
$ git show <commitid>:filename
I wrote the wrong thing in a commit message
If you wrote the wrong thing and the commit has not yet been pushed, you can do the following to change the commit message without changing the changes in the commit:
$ git commit --amend --only
This will open your default text editor, where you can edit the message. On the other hand, you can do this all in one command:
$ git commit --amend --only -m 'xxxxxxx'
If you have already pushed the message, you can amend the commit and force push, but this is not recommended.
If it's a single commit, amend it
$ git commit --amend --no-edit --author "New Authorname <[email protected]>"
An alternative is to correctly configure your author settings in git config --global author.(name|email) and then use
$ git commit --amend --reset-author --no-edit
If you need to change for multiple commits, you can use
$ git -c rebase.instructionFormat='%s%nexec GIT_COMMITTER_DATE="%cD" GIT_AUTHOR_DATE="%aD" git commit --amend --no-edit --reset-author' rebas
Git Flight Rules is a crowdsourced troubleshooting guide: for almost any git 'uh-oh' moment, it tells you exactly what happened and the commands to fix it, modeled on NASA's astronaut flight rules.