How to use github properly. Just the basics: cloning a repo, making a change, and uploading the change back to github.
sources
https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository
https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository
https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes
how-to: summary
This is the super simple version with no commentary, and just a bit of explanatory text. Remember, the warnings come after the spells.
Getting set up
Install git
sudo apt-get install git
configure login email address
Set your github name.
git config --global user.name "YOUR NAME"
set your email address to private in github. Go there:
profile --> settings --> emails --> [] keep my email address private
Set the global github private email address.
git config --global user.email "username@users.noreply.github.com"
Double-check the email address.
git config --global user.email
connect to github with https
Hold onto the github password for a while.
git config --global credential.helper cache
Extend the password timeout period.
git config --global credential.helper 'cache --timeout=1800'
making changes to a current project
First, create a local clone of your fork: I'm using the MPI Torch project as an example.
mkdir ~/projects && cd ~/projects
git clone https://github.com/umhau/mpiT.git
cd mpiT
Create or modify a file in your local repository, then stage it.
echo "Extra! Extra! Read all about it!" >> README.md
touch laughing.txt && echo "hahahaha" > laughing.txt
git add README.md
git add laughing.txt
Monitor the staging process.
git status -s
Commit your staged files prior to uploading.
git commit -m "write a commit message here"
Check that 'origin' is the correct short name of the github server.
git remote -v
Push your commit to the github server
git push origin master
how-to: annotated version
Getting set up
Install git
sudo apt-get install git
configure login email address
Tell git your name - who to credit your work to.
git config --global user.name "YOUR NAME"
configure your email address - you can keep your real one private by combining your github username with a special github email domain. First, change github settings to keep the email address private. Go to:
profile --> settings --> emails --> [] keep my email address private
Now configure your email address. This tells git and github to use the private email address for all repositories downloaded to the computer.
git config --global user.email "username@users.noreply.github.com"
You can confirm the email address with this command:
git config --global user.email
connect to github
We're going to use HTTPS to download, and we're not going to deal with 2-factor authentication, and we are going to use a password manager to avoid repeatedly entering passwords.
This tells git to hold onto the github password for a while.
git config --global credential.helper cache
And this controls how long that 'while' is - default is 15 minutes, but I feel like 30 (it's counted in seconds).
git config --global credential.helper 'cache --timeout=1800'
making changes to a current project
We'll assume, for the moment, that you have an ongoing project - this is going to be either a copy ("fork") of someone else's project, or something you've already started uploading to github and want to keep working on The Right Way. Since this is your ongoing project, you own it and have full permissions to mess with it. You're also not going to be merging it with some other repository.
The idea behind the many steps involved with making changes (staging, the head, etc.), is to allow for both minor and major changes - a simple tweak by one guy vs. a complete overhaul vs. a new feature. The really big changes can be made in forks of the project that get merged with the original (upstream) version, the sizable changes can be made in branches of the current fork (or original repository), and the small changes can be verified by the rest of the team prior to being added directly to a branch (master/primary or otherwise) of the current repository.
It's a great system, but a real pity there's no simple way to get started.
First, create a local clone of your fork: I'm using the MPI Torch project as an example. Make sure you have a place to put it.
mkdir ~/projects && cd ~/projects
The .git link you need to download with is on github -- look over on the right where the opened menu is:
The link is over on the left. After you've got it, run the command below (or your equivalent, on a project you can make changes to).
git clone https://github.com/umhau/mpiT.git
cd mpiT
Now you've "created a local clone" of your repository/fork. Nice! You've got the code on your computer. I'm pretty sure that everything else you do with github related to that 'local clone' has to be done while you're 'within the directory' -cd'd inside mpiT (in this case).
As you change files, git will be watching - anything you change will be marked modified, anything you don't change will be marked unmodified. You can stage a file whenever you want to record a snapshot of your current progress (and you can undo snapshots, too, but that's not needed here). Staged files are added to your next commit.
A commit is a collection of files that are being prepared for upload - until the commit is pushed, it's all local to your machine.
Let's pretend you go ahead and
make some changes to the code you downloaded. Maybe you added something to the README.md. Remember, you're still in the ~/projects/mpiT/ directory:
echo "This is super important stuff!" >> README.md
If we check which tracked files have been changed, git will tell us that README.md has been modified, and has not yet been 'staged' for the next commit to the server.
git status
if you're ready to stage the file, run
git add README.md
you can also use the git add command on a directory, and it will recursively stage everything in the directory for the next commit.
If you want to add a new file to the repository
echo "hahahaha" > laughing.txt
you have to tell git to track it -
git add laughing.txt
and it will be automatically staged (what else was git supposed to do with it?).
Also note that if you stage a file, and then edit it again, the staged version will remain whatever version you had when you ran git add. If you want to stage the new version, you have to run git add again.
Use git status to monitor the version of each file being staged. Use
git status -s
to get a less 'verbose' version of the status output. When everything has been edited and modified and staged properly, use
git commit -m "write a commit message here"
to upload your changes. Keep the quotation marks when you write your message, which is intended to tell others what changes you made. If you don't include the -m "commit message" bit, then you'll be prompted for a longform message in a command line text editor.
While in the directory, git will automatically name the server you cloned from "origin". That way, when you need to do something related to the online github version of your code, you can reference it with "origin".
Here, you can check the name of the remote repository you're working with. A "remote repository" is what you call the online (i.e., not-on-your-laptop) version of the code. You can
add more, but that's not needed here.
git remote
You should see the name used to refer to the repository -
origin
just as discussed above. And if you want to see exactly what server 'origin' refers to, you can run
git remote -v
to see a list - in my case, probably something like this:
origin https://github.com/umhau/mpiT.git (fetch)
origin https://github.com/umhau/mpiT (push)
Back on track: let's upload the commit you assembled (the
commit: your collection of staged files). It's called
pushing, and you do it like this:
git push origin master
Now the changes you made on your computer have been uploaded to github. That's it!
