git mini guide
You have a couple of different choices for Git software on your computer. You can use any Git software you want as long as you make sure everything is working correctly.
Also known as Git Bash. Installation instructions for various platforms can be found here.
The GIT GUI also provides command line functionality. Note that when merging different versions, unresolved conflicts will cause extra text to be inserted in the code file, and this breaks the code. It is easy to miss these when using a GUI. Do not leave any conflicts unresolved when committing.
Git Extensions is preferred by some CSL users.
Github Desktop is platform-independent and maintained by GitHub.
This is a mini-tutorial on how to use git. More detailed instructions can be found in the extended tutorials under the additional resources section. The description below assumes you are using the command line; the same workflow applies for git GUIs.
Your interaction with git should follow the following workflow:
- You should add new files to your local repository
- You should edit files using your favorite editor.
- After you add a new file and/or edit an existing file, you should commit your changes locally.
- After you have committed one or more changes locally, you need to pull any changes that have been made in the remote repository (e.g., on GitHub). Git will try to merge your committed changes with the ones on the remote repo.
- If the merge succeeds, you can proceed to push your commits the remote repository; if it fails, you need to resolve any conflicts, and go back to step 3.
Overall, you should always remember to commit before you pull, and pull before you push.
commit -> pull -> push
You can clone a repository using git clone. For example
git clone git@github.com:neu-spiral/SPIRAL-Handbook.gitclones the repository that contains this wiki. Most repository hosts, like GitHub, GitLab, and Overleaf, provide easy ways for cutting and pasting the text that should appear after git clone part of this command for a specific repository.
This will create a directory with your local copy of the remote repository (in this case, the directory would be SPIRAL-Handbook. You can rename the directory if you desire. All commands described below should be executed from within this directory.
After you have created file myfile, you can add it to your local repository by typing
git add myfileFiles in the directory holding your local repo that are not "added" thusly are untracked: they are not considered part of the distribution, are not synched with the remote repo, and are not version-controlled (you cannot recover them if you delete them). The rule of thumb is that you should add source files to your repo, but never add binary files compiled or derived from your source files.
You can remove a file via
git rm myfileNote that this also deletes the file.
After you have made some changes on a file, or added a new file, or resolved a conflict, you need to commit your changes to your local repository by typing
git commit -a -m "Message describing by edits"Try to provide descriptive messages.
To synch changes made at the remote repo with your local repo, you need to pull any remote commits by typing
$ git pull origin master
Origin stands for the remote label and master the branch name you are working on. You should always commit before you pull. If there are changes in files in your local repo that have been edited but not committed, git will complain and will not allow you to pull. If there are remote changes on the same files as the ones you edited, then the repo will try to merge them. A successful merge may prompt you to enter a message (using the vi editor). A failed merge will ask you to resolve conflicts.
To push changes made at your local repo to the remote repo, you should first (a) commit them, and then (b) pull any remote commits. Only then, and presuming there are no conflicts, you can go ahead and push your changes to the remote repo by typing:
$ git push origin master
Origin stands for the remote label and master the branch name you are working on. If the remote repo is out-of-synch, it will ask you to commit your changes and pull; you will not be able to push before you pull.
After a failed merge (that happened during a pull), git will ask you to resolve conflicts. It will tell which files contain conflicts. To resolve the conflicts, you need to open each one of these files and locate places that contain something like this:
<<<<<<< HEAD
This is something that was written in your local repo, that git did not know how to merge with the remote repo.
=======
This is something that was written in the remote repo, that git did not know to to merge with your local repo
>>>>>>> remote-branchYou should use your best judgement of text to keep (yours, above the =======, or the remote text, under the =======) or whether you should somehow blend the two.
After you have edited all the files that contained such conflicts to resolve them, you should commit these edits, and then try to pull again.
Note that if someone has been editing the same files while you were resolving conflicts, this may give rise to more conflicts that need to be resolved, either manually or via git's merge. If you want to avoid conflicts, it may be a good idea to (a) split your project into multiple files, and/or (b) agree with your collaborators on which part of the project/file each of you should be working on. Such coordination is usually conflict-free.
You can check the status of your repo w.r.t to the remote via
git statusYou can also see a log of all commits, local and remote (after you have pulled), via
git logWhen you clone a repository, github creates a 'remote'. A remote describes the github repositories you are working with. To view your setup remotes type
$ git remote -v
origin https://github.com/neu-spiral/RFMLS (fetch)
origin https://github.com/neu-spiral/RFMLS (push)
Origin is the label you assign to the given repository. To remove or add a remote:
$ git remote rm origin
$ git remote add origin https://github.com/neu-spiral/RFMLS
If you are interested in using an SSH with github, and not having to enter your username and password for each pull and push, please see the following steps:
- Create an ssh-key if you do not have one. To check, see if you have a public rsa key:
$ head ~/.ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1{...}== costarendon.b@discovery4.neu.edu
You may or may not have an email assigned to the key, it is okay if you don't have one.
- If you do not have a public rsa key you may create one with
ssh-keygen. You will be prompted with the following:
$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
Enter file in which to save the key (~/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ~/.ssh/id_rsa.
Your public key has been saved in ~/.ssh/id_rsa.pub.
The key fingerprint is:
80:5f{...}
The keys randomart image is:
+--[ RSA 2048]----+
| oo ...+. |
|.oo . .ooo |
|o .o. . .o . |
| o ...+o. |
| o .=.=S |
| . .Eo . |
| |
| |
| |
+-----------------+
Save the key in the default location ~/.ssh/id_rsa. You do not need to create a passphrase. If you are using multiple devices, it is recommended to create a separate ssh key for each device (personal laptop, DGX, Discovery Cluster...).
-
Go to github.com/settings/keys, or go to github.com and click dropdown menu at the top-right on navigation bar > Settings > SSH and GPG keys. Click on 'New SSH Key'. Copy the whole ssh-rsa key including the header from ~/.ssh/id_rsa.pub into the text field. It should start with something like: 'ssh-rsa AAA...'.
-
Remove your remote and re-add it with the following link:
$ git remote rm origin
$ git remote add origin git@github.com:USER/REPOSITORY
In the case of the RFMLS repository, you would add it as:
$ git remote add origin git@github.com:neu-spiral/RFMLS
Your next pull or push should now not require username and password!
- Resources to learn Git
- Git Tutorials:1, 2, 3
- Git CheatSheet
- GitHub Learning Resources
- GitHub Help
