Getting Started

Resources

Most open source projects are on GitHub. Checkout GitHub Explore to simply “explore” what’s out there. For example you can view a list of top projects for related to government or social impact.

Advice: Use Atom as a text editor for working on git projects! It color codes files (green for added, orange for modified) and allows you to view the fancy side-by-side changelog of a file immediately before checking it in. You can even stage, commit and resolve merge conflicts using only the git-integrated UI.

Also, check out GitHub’s reference on user autolinks to things like commits, issues, or users.

GitHub Pages

Use GitHub Pages to publish a site for a GitHub account (personal/organization), as well as for hosting GitHub projects like:

  • blog or website using jekyll, at username.github.io (source)
  • webapp project using the /docs folder in project master branch, and find the project at username.github.io/project (source)

Contributing to Open Source Projects

Checkout https://opensource.guide/ by GitHub. They have a specific section on How to submit a contribution

A good accepted standard for making a contribution is:

  1. Fork the repo (using online GitHub GUI)
  2. git clone <URL> your forked version to local machine
  3. git checkout -b <BRANCH> a new branch named after your bug fix or feature
  4. Make your changes, and make sure you adhere to project standards, and pass any project tests
  5. git add . and git commit -m "YOUR CHANGES EXPLANATION", then git push -u origin <BRANCH> to add your new branch to your forked repo’s origin
  6. Submit a pull request (using online GitHub GUI) with a description of your changes, referencing the relevant open issues

Config

Check install

git --version

Configure credentials

git config --global user.name "Kain Nanne"
git config --global user.email "kain.nanne@gmail.com"
git config --global --list

Create SSH key

ssh-keygen -t rsa -C "kain.nane@gmail.com"

Start Project

Easiest way to start is create a repository on Github or GitLab, then clone it to local.

cd projects
git clone <URL>

Alternatively, we could initialize a new local directory, and add the repo as remote origin.

md repo
cd repo
git init
git remote add origin <URL>
git push -u origin master

Workflow

For the proper workflow, download the GitHub workflow.pdf or view it online. Or, see guide on Contributing to Open Source

If you have cloned a repo, replace REMOTE with origin in the following commands.

Fetch all or pull remote branch

git fetch <REMOTE>
git pull

Create a branch

git checkout -b <BRANCH>

Now make some changes in the repo, and add (all) those changes

git add .
git commit -m "MESSAGE"

Check status of changes

git status

Push changes to repo

git push

Merge changes

git checkout <BRANCH>
git merge master

Situations

Below are some scenarios that you may find yourself in, and some helpful tips on how to get out.

I highly recommend using Atom while resolving conflicts. It is a text editor made by GitHub and therefor contains very handy options to identify and resolve conflicts with a couple of clicks.

Pull with Conflicts

git checkout feature
git pull

In case of conflicts and you want to simply keep the changes on your local feature branch (ours) of a specific file, and apply them on top of the files being pulled in, do the following:

git checkout --ours <FILE>.py
git add .
git commit
git push

In case of being stuck in vim after commit, type :wq

Rebase Local Master (with Conflicts)

Do not rebase (public) commits that exist outside your repository - Pro Git Book

For further notes on this issue, check out this tutorial by Atlassian, which has a great visual walkthrough.

Otherwise, if you still want to do this…

git checkout <FEATURE-BRANCH>
git rebase master

This rebase is the same as a pull, however “ours” and “theirs” are switched. In case of conflicts and you want to simply keep the changes from the new feature branch (theirs) of a specific file, and apply them on top of master, do the following:

git checkout --theirs <FILE>.ipynb
git checkout --theirs <FILE>.xml
git add .
git rebase --continue

Note that a rebase merge works by replaying each commit from the working branch on top of the branch. Because of this, when a merge conflict happens, the side reported as ours is the so-far rebased series, starting with , and theirs is the working branch. In other words, the sides are swapped. [Git docs](https://git-scm.com/docs/git-rebase#git-rebase---merge)

In case you want to force rebase, resolving all conflicts using the using new feature branch (theirs), do the following.

git checkout <FEATURE-BRANCH>
git rebase -s recursive -X theirs master

Mistakes Were Made

List previous commits, limit 1

git log -n 1

Reset current HEAD and index to last commit

git reset --hard

Remove untracked files from the working tree

# show to be deleted
git clean -n
# perform deletion
git clean -f

A Messy Past

“Prune” is the command for cleaning up the log files or git database. It will remove old commits and associated file history which do not exist in the current branches’ ancestry.

Prune all unreachable objects from the object database - git website

You can run git prune to simply do this locally.

However, git remote prune origin will remove local history no longer on referenced on remote. You will need to commit after this.

Additionally, adding --prune to a git fetch will do this local cleaning while fetching new objects.

Note that none of the prune commands delete branches, and there is no magical command from git to delete old branches which do not have remote references. Therefore it’s better to delete old branches individually with git branch -d <BRANCH>.

Notable Commands

Create local branch from remote

git checkout origin/<BRANCH> -b <BRANCH>

Create remote branch from local

git push --set-upstream origin <BRANCH>
# or
git push -u origin <BRANCH>

List branches

git branch --list

Navigate to branch

git checkout <BRANCH>

List all committed files

git ls-tree --name-only <BRANCH>

List all uncommitted files

git ls-files --others

Unstage everything, a specific file, or a directory (after staging all with git add .)

git reset
git reset <FILE>
git reset -- <DIR>

Edit last commit message before pushing.

git commit --amend

You will be in VIM. Hit Esc then type :wq to write and quit