Requirements
This tutorial assumes that you have already worked through the tutorial on GitHub.
Introduction
Git is a version control system that allows you to track changes in software over time. The workflow usually uses several branches, which each contain their own changes, and these then have to be merged at some point. The branches allow teams to work together effectively. See the Workflow section below for more information.
Installation
Only use the steps below if you just worked through the GitHub tutorial and this is the first time you use Git. If not, go to the next section.
First, connect to your jail and install Git:
sudo pkg install git
Then we set the user email and user name:
# replace $EMAIL with the email address you used to register at GitHub git config --global user.email "$EMAIL" # replace $NAME with your name git config --global user.name "$NAME"
We will now create a new repository named homepage and then commit it to GitHub. We will create a directory in www so that the result is available in the browser. Run the following lines:
cd ~ cd www mkdir homepage cd homepage echo "# homepage" >> README.md git init git add README.md git commit -m "first commit" # replace $GITHUB_USERNAME with your GitHub username git remote add origin git@github.com:$GITHUB_USERNAME/homepage.git git push -u origin master
At this point you have to accept fingerprints for a new host (so enter yes) but then you will get a permission denied message. The reason is that we still have to set up authentication through SSH. Execute the following steps:
# replace $EMAIL with your point park email ssh-keygen -t rsa -b 4096 -C "$EMAIL" Enter a file in which to save the key (/home/username/.ssh/id_rsa): [Press enter] Enter passphrase (empty for no passphrase): [Press enter] Enter same passphrase again: [Press enter]
This generated the key. Now we need to output the key so we can copy it to GitHub:
cat ~/.ssh/id_rsa.pub
Copy the text that is displayed after that command and enter it as an SSH key into GitHub. This can be done in Settings (available in the top right dropdown menu in the black bar) and click on SSH and GPG keys. Then create a new SSH key and paste the earlier copied text in the Key area. Now, we can rerun the push command and this time it should work:
git push -u origin master
Cloning a Repository
If you already worked through the above steps and want to clone an existing repository, simply run this:
git clone git@github.com:$GITUSERNAME/$REPOSITORY.git
where you have to replace $GITUSERNAME and $REPOSITORY with the appropriate values.
Committing Changes to a Repository
There are usually four steps in updating your repository after making changes. First check what changed by running
git status
If anything has changed it will be displayed. Then you can add those changes to be part of a commit by running
git add file1 file2 file3
where file1, file2, and file3 are files that have been changed. Then we commit the changes and add a descriptive message to it:
git commit -m "some message"
And we push it to our GitHub remote repository.
git push
Note that changes are committed to the master branch by default. You can change this behavior, see the next section for details.
Workflow (More Advanced)
Normally when working in a team, you would not commit changes directly to the master branch but work on your own branch first, and then create a pull request to merge those changes into master. So first, we create a new branch to develop a new feature. Make sure you are somewhere inside the directory under git control, there should be no uncommitted changes, and you are on the master branch:
git checkout -b new_feature_branch
This creates the new branch with as base the master but now you can make your changes without affecting the master. Follow the steps in the previous section to commit changes to the new_feature_branch. After you are done, make sure to push the changes to GitHub.
Creating a Pull Request
The final step is to create a pull request to merge the changes that were made in the new_feature_branch back to master. In GitHub on the main page of the repository, select the new_feature_branch from the drop down. Then click on the New pull request button right next to it, and on the next page click on New pull request once again (the green button).
At this point, the pull request is usually reviewed by the appropriate people. Note that under Files changed you can see the differences in a very nice way. Once everyone is onboard, you can click on Merge pull request to do the actual merge.
Pulling in Changes from Master
One of the issues with the described workflow is while you are working on your branch, the master branch is updated by someone else. Therefore, you should pull the changes from master occasionally by running:
git pull origin master
Occasionally, there may be conflicts that you have to resolve. If that happens, you should open the files that have conflicts and look for these sections:
>>>>>>>>>>>>>>>>>>>>>>>>>>>>> section a ============================= section b <<<<<<<<<<<<<<<<<<<<<<<<<<<<<
The part under section a comes from one branch, and section b comes from the other branch. You have to decide what to keep and what to remove, which is usually clear from the context. At the end, no >>>>, =====, or <<<< should be left in the file. Then do
git add conflict_file_1 conflict_file_2
followed by a git commit and git push. That should do the trick. Note that this strategy also works when a pull request cannot be merged because of conflicts.