Getting Started With git

Setup and Notes

All of the following assume you are working in a terminal (bash for windows works otherwise use the git bash client, mac/linux can use the built in terminal). Download git from here, it's a version control software run through a command line interface. To initially configure git run the following commands:

git config --global user.name "YOUR NAME HERE"
git config --global user.email "YOUR GITHUB EMAIL ADDRESS"

Include the quotation marks but replace the text with the correct information. You can check this with the following command: git config -l

Now cd into the folder you want to have the repository in, note that when the repo gets downloaded it will create a folder with the name of the repo. Once you are in the right directory you can clone the repo with the following command:

git clone https://github.com/drjdlarson/gasur.git

Note the url can also be found on the "clone or download" button on the repo's home page. Now cd into the new folder, and commands can be run.

Creating an SSH key

To make it so a password doesn't need to be entered every time a push is made it's useful to setup ssh keys. This can be done by running the following commands:

ssh-keygen -t rsa -b 4096 -C "YOUR_GITHUB_EMAIL"

Press enter to choose the default location and press enter again to leave the passphrase empty. Now github needs to know about the key so go here and click "New SSH key" choose some title for it, then in the key field you need the result of the previous command. This can be obtained by copy and pasting the result of

cat ~/.ssh/id_rsa.pub

Now cd into the repo and switch from HTTPS to SSL by running the following

git remote set-url origin git@github.com:drjdlarson/gasur.git

Typical git Workflow

Git uses branches to keep different features separate and help with version control. The main branch is called master, this is usually used for the latest stable release of code. Then additional branches are made for each feature that is to be implemented. Git works by telling it to "add" files to be committed, then to "commit" them with a message and then "push" them to the remote (sometimes requiring a "pull" if someone else has pushed code to the "remote", ie what is seen on github.com). Note, these commits depend on the current branch you are on.

To accomplish these tasks the following would be run:

git pull

gets any changes on the remote branch not currently on your local machine, then after changing a file you can run

git add -u

to add the files that have been updated to your commit. Note if you created a new file you need to run

git add RELATIVE_PATH_TO_FILE

to tell git to start tracking the file and add it to the commit. It's important that only 1 person is editing a file at a time, even if they are on different branches. This helps prevent merge conflicts which arise when branches are combined but there are conflicts in files have being updated at different times with different information.

Now to actually make a commit run

git commit -m "MESSAGE"

Leave the quotes but change the message to reflect the changes made. Now to put this commit on the remote run

git push

Other Useful Commands

To check what branch you are on and if you have any commits not yet pushed to the remote you can run

git status

If you make some changes but haven't committed anything and want to go back to what is on the remote then run

git reset --hard

to switch to a different branch run

git checkout BRANCH_NAME

replacing BRANCH_NAME with the name of a branch, if the branch doesn't autocomplete or doesn't switch then change to master and do a git pull and try again.

To create a branch, go online to the repo's webpage and click the branch drop down box, then type the name of a new branch and click create new branch.

Once a branch is ready to be added to master and be part of the next stable release, go to the website and navigate to the branch. Then click new pull request and follow the steps, a request will be sent and if approved the code will become part of the master branch. Now the other branches need to run the following command to stay up to date with the master branch;

git pull origin master