This article describes basic steps regarding to working with git and also gives several tips, which can be useful and are not usually covered in tutorials.
To start working with git you can create own repo with
git init or you can clone an existing repository, for example:
git clone email@example.com:droolsjbpm/jbpm.git
It’s recommended to prefer SSH url, because HTTPS connection is less reliable.
You can make changes to your project and add them to next commit. And then commit the changes. You should always write a brief description of your commit.
git add --all git commit -m "Refactored module X to work with Y."
After making necessary commits you can share your changes with other by pushing them to the server. Usually the remote on the server is called origin or upstream. The convention is that main repo of the project for all people is usually called upstream and personal forked repo on Github is called origin. I think it is a good habit to also specify a branch you want to push. For example:
git push origin master
It is good idea to regularly check for changes from the others to work with current code and prevent conflicts. The first one just downloads the changes. The second one adds the changes of others to your master branch and puts your commits on the top as the latest ones. This principle keeps linear history and is called rebasing.
git fetch upstream git rebase upstream/master
You may easily end with unwanted changes in the repository and there seem to be no steps to revert the state back. In this cases reset can help, but it clears your changes and makes your repository the same as remote.
git reset --hard
Getting information about your repository
Here are several useful commands to get more information about your repository. So to check status of your repository, list all branches or remotes:
git status git branch -a git remote -v
Sometimes it is necessary to check commit history of your project. Log is the basic command, but much better is to install tool called
tig. It allows you to inspect history in command line interface in more comfortable way than simple log.
git log tig
Interested in who screwed something up? You can check who changed which lines in selected file.
git blame README.md
Working with branches
Branches are powerful feature of Git. Instead of Subversion, the branches are cheap and simple to use. To create a new branch “MyBranch” and start working with it, just type:
git checkout -b MyBranch
This will create new branch by copying the current branch and automatically the MyBranch is switched. To change branch, for example to work again with master:
git checkout master
You can create topic branches, make changes, push them to your origin and in Github web interface make pull requests to upstream. Sometimes there are changes done in the upstream during the work on a pull request. Then you cannot simply push, because when you rebase updates from master to your topic branch, the commit IDs will change. You can use a force push here:
git checkout MyTopicBranch git rebase master git push --force origin MyTopicBranch
However after you are done, you may need to delete old branches. The first one deletes remotely, the second one locally.
git push origin :MyTopicBranch git branch -D MyTopicBranch
How to rebase a Github pull request to your project
Imagine the situation. Your project is hosted on Github. Somebody forks your repository and creates a pull request to your repo. Github offers you a green button “Merge pull request” if there are no conflicts to automatically merge the changes of a contributor to your repository. This will add the changes to your upstream but will create an additional merge commit. Better approach can be the git rebase operation, which has some significant advantages over merge. The main reason is clean and linear history of the commits. I do not know why, but Github does not have a button “Rebase pull request”. So to utilize advantages of rebase approach the following git command can simplify your life (taken from blog of Stuart Douglas):
git pull --rebase upstream pull/$no/head git push upstream master
Where the upstream is the name of the Github remote where the pull request was created and $no is the identification number of the pull request. This way you can rebase the changes to your local working repository, check them, make corrections if needed, run unit tests and then push back to your upstream/origin on the server. Pushing to repository also automatically closes the pull request.
Creating a patch file
One of the simplest approaches is to commit your changes, create a patch file (for example for your co-workers) and reset hard to a previous commit:
git format-patch -M -1 git reset --hard previous_commit_id
Applying a patch
Later if we want to apply a patch file to our repository the steps are following:
git apply patch_file_name.patch