Git and GitHub for beginners (ZoL edition)
This is a very basic rundown of how to use Git and GitHub to make changes.
Recommended reading: ZFS on Linux CONTRIBUTING.md
First time setup
If you’ve never used Git before, you’ll need a little setup to start things off.
git config --global user.name "My Name" git config --global user.email email@example.com
Cloning the initial repository
The easiest way to get started is to click the fork icon at the top of the main repository page. From there you need to download a copy of the forked repository to your computer:
git clone https://github.com/<your-account-name>/zfs.git
This sets the “origin” repository to your fork. This will come in handy when creating pull requests. To make pulling from the “upstream” repository as changes are made, it is very useful to establish the upstream repository as another remote (man git-remote):
cd zfs git remote add upstream https://github.com/zfsonlinux/zfs.git
Preparing and making changes
In order to make changes it is recommended to make a branch, this lets you work on several unrelated changes at once. It is also not recommended to make changes to the master branch unless you own the repository.
git checkout -b my-new-branch
From here you can make your changes and move on to the next step.
Testing your patches before pushing
Before committing and pushing, you may want to test your patches. There
are several tests you can run against your branch such as style
checking, and functional tests. All pull requests go through these tests
before being pushed to the main repository, however testing locally
takes the load off the build/test servers. This step is optional but
highly recommended, however the test suite should be run on a virtual
machine or a host that currently does not use ZFS. You may need to
flake8 to run the
sh autogen.sh ./configure make checkstyle
Committing your changes to be pushed
When you are done making changes to your branch there are a few more steps before you can make a pull request.
git commit --all --signoff
This command opens an editor and adds all unstaged files from your branch. Here you need to describe your change and add a few things:
# Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # On branch my-new-branch # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # modified: hello.c #
The first thing we need to add is the commit message. This is what is displayed on the git log, and should be a short description of the change. By style guidelines, this has to be less than 72 characters in length.
Underneath the commit message you can add a more descriptive text to your commit. The lines in this section have to be less than 72 characters.
When you are done, the commit should look like this:
Add hello command This is a test commit with a descriptive commit message. This message can be more than one line as shown here. Signed-off-by: My Name <firstname.lastname@example.org> Closes #9998 Issue #9999 # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # On branch my-new-branch # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # modified: hello.c #
You can also reference issues and pull requests if you are filing a pull request for an existing issue as shown above. Save and exit the editor when you are done.
Pushing and creating the pull request
Home stretch. You’ve made your change and made the commit. Now it’s time to push it.
git push --set-upstream origin my-new-branch
This should ask you for your github credentials and upload your changes to your repository.
The last step is to either go to your repository or the upstream repository on GitHub and you should see a button for making a new pull request for your recently committed branch.
Correcting issues with your pull request
Sometimes things don’t always go as planned and you may need to update
your pull request with a correction to either your commit message, or
your changes. This can be accomplished by re-pushing your branch. If you
need to make code changes or
git add a file, you can do those now,
along with the following:
git commit --amend git push --force
This will return you to the commit editor screen, and push your changes over top of the old ones. Do note that this will restart the process of any build/test servers currently running and excessively pushing can cause delays in processing of all pull requests.
Maintaining your repository
When you wish to make changes in the future you will want to have an up-to-date copy of the upstream repository to make your changes on. Here is how you keep updated:
git checkout master git pull upstream master git push origin master
This will make sure you are on the master branch of the repository, grab the changes from upstream, then push them back to your repository.
This is a very basic introduction to Git and GitHub, but should get you
on your way to contributing to many open source projects. Not all
projects have style requirements and some may have different processes
to getting changes committed so please refer to their documentation to
see if you need to do anything different. One topic we have not touched
on is the
git rebase command which is a little more advanced for
this wiki article.