download changes from git

So this should work when I've got multiple copies of the repo on different computers.  Run this (and the first two commands are optional) to refresh the local repo to the latest version.

git reset --hard HEAD
git clean -f

Those two will remove any local changes.  The last one actually gets the new version.

git pull

branches on github

While github recommends that branches be made locally, I prefer the data security of keeping them off-site.  This is how to manage and merge a branch that's kept remote, on github.

https://github.com/Kunena/Kunena-Forum/wiki/Create-a-new-branch-with-git-and-manage-branches
https://try.github.io/levels/1/challenges/19
http://stackoverflow.com/a/6232535

Checkout a new branch on your computer (this is not something on github)

git checkout -b <branch>

Push the branch to github - now there's a new branch up there.

git push origin <branch>

And to switch to a different branch, use

git checkout <branch>

git cheat sheet

Still learning the system.

git init                |  Tell git to start watching the directory
git clone <repo>        |  Get a local copy of the repository

.gitignore              |  Contains patterns of files to ignore
git rm --cached <file>  |  Stop tracking the file in git

git add <file>          |  Stage a snapshot of the file
git rm <file>           |  Stage the file's removal
git mv <a> <b>          |  Rename 'a' to 'b' and stage the change

git status              |  Staging status of files
git status -s           |  Simpler version of status

git commit              |  Upload to server
git commit -m "txt"     |  Commit, with inline message

basic github - working with a cloned repository

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!