Git Version Control Tutorial

Table 1. Terminology Summary
Term	Description
`plumbing`	Low-level toolkit commands.
`porcelain`	User-friendly front end commands.

Stage	Description
committed	The content of the file is safely stored in the repository.
staged	A modified file is marked for inclusion with the next commit.
modified	A file git is aware of has been modified but is not commited to the repository yet.

#!/usr/bin/env bash

# -----------------------------------------------------------------------------
# Small script to push upstream without a fuss
# -----------------------------------------------------------------------------

# -----------------------------------------------------------------------------
# Setup
# -----------------------------------------------------------------------------
set -o errexit
set -o nounset
set -o pipefail

# check bash version compatiblity requires 4.2 or better
shopt -u compat41 2>/dev/null || {
  echo -n "\nBash Version 4.2 or higher is required!\n";
  exit 127;
}


# -----------------------------------------------------------------------------
# Globals
# -----------------------------------------------------------------------------
declare -r SCRIPT=${0##*/}
declare -r VERSION=0.3.1
declare -r AUTHOR="Urs Roesch <github@bun.ch>"
declare -r LICENSE="GPLv2"
declare -g FORCE=""
declare -g REMOVE=""

# -----------------------------------------------------------------------------
# Functions
# -----------------------------------------------------------------------------
function usage() {
  local exit_code=${1:-1}
  cat <<USAGE

  Usage:
    ${SCRIPT//-/ } [options]

  Opttions:
    -h | --help    This message
    -f | --force   Force a push to upstream
    -r | --remove  Remove the repository from upstream
    -V | --version Display version and exit

  Description:
    Origin push to upstream without a fuss. Exludes pushes to master.

USAGE

  exit ${exit_code}
}

# -----------------------------------------------------------------------------

function parse_options() {
  while [[ ${#} -gt 0 ]]; do
    case ${1} in
    -h|--help)    usage 0;;
    -f|--force)   FORCE="true";;
    -r|--remove)  REMOVE="true";;
    -V|--version) version;;
    -*)           usage 1;;
    esac
    shift
  done
}

# -----------------------------------------------------------------------------

function version() {
  printf "%s v%s\nCopyright (c) %s\nLicense - %s\n" \
    "${SCRIPT}" "${VERSION}" "${AUTHOR}" "${LICENSE}"
  exit 0
}

# -----------------------------------------------------------------------------

function current_branch() {
  git rev-parse --abbrev-ref HEAD
}

# -----------------------------------------------------------------------------

function push_origin() {
  local branch=$(current_branch)
  if [[ ${branch} == master ]]; then
    echo "Not pushing master!"
    exit 1
  fi
  git push ${FORCE:+-f} origin ${REMOVE:+:}${branch}
}

# -----------------------------------------------------------------------------

function push_tags() {
  git push --tags
}

# -----------------------------------------------------------------------------
# Main
# -----------------------------------------------------------------------------
parse_options "${@}"
push_origin
push_tags

1	`0` is the original git repository format. With git 2.7 extensions were introduced if such extensions exist the version can be bumped to `1`.
2	`filemode` is generally set to `true` on Unix like systems but for say Windows where the traditional Unix file permissions are not used it should be set to `false`. This prevents mismatches of file permission in the index and on disk.
3	Bare repositories are mostly used on sharing platforms such as GitHub, GitLab or Bitbucket. The structure is different from a working repository.
4	For working directories the default is `true` as all changes should be logged. Bare repositories should have a value of `false`.

1	Create a file with content.
2	Execute the `status` command. Git has recognized the file but does not yet track it.
3	Status' first line shows the branch name. In this case `master`.
4	Git tries to inform you about possible next steps like in this case to use `git add`.
5	Add all files to the staging area. The dot `.` recurses through all sub-directories. Only adding a single file is done with `git add first-file.txt`. Shell wildcards also work e.g. `git add *txt`.
6	Note the message about taking a file out of cache should you have mistakenly commited to stage.
7	Git now knows about the file `first-file.txt`. But remember it has not been yet commited!

1	A commit message is always required. With the `-m` aka message argument it is passed via the command line. Otherwise an editor would appear prompting for input.
2	The `root-commit` is the first commit and does not have a parent.
3	Git is showing file and change statistics for the commit.
4	Newly created files are displayed with the file permission.
5	The repository is now clean, meaning there are no pending changes in the working directory or the staging area.

1	The first line is the most important it shows the commit’s unique identifier a hex encoded SHA1 hash. In newer version of git the log is `decorated`, meaning shows additional information e.g. the `HEAD` of the repository.
2	The authors name. Changing this information is discussed in module 2.
3	The date of the commit.
4	The commit message.

1	Creating a dummy file in the `tmp` directory.
2	Check the `status` of the repository in short form. The two leading question marks indicate git has found new files in the `tmp` directory.
3	The `tmp` directory should exist but not be tracked by git. Hence a `.gitignore` file in the top-level with the content tmp is created.
4	Once more running a `status` check shows the files in `tmp` are no longer considered. However the `.gitignore` file is not marked as untracked.

1	Git’s common options.
2	Git’s porcelain commands structured by topic.
3	Further commands to display more extensive help.

1	Adding the user’s full name global configuration file.
2	Adding the user’s email to the global configuration file.

1	List of files that have been change and the number of lines added `+` or subtracted `-`.
2	Summary of the accumulated changes. The same message shown during the commit.

1	Stage the `.gitignore` file.
2	Commit everything staged.
3	Verify the with `git log`. Notice the `HEAD` has moved to the commit. And two commits are shown.

1	`--shared` specifies the Git repository can be shared amongst several users. Users belonging to the same group may push into that repository.
2	The naming convention for bare repositories is to suffix it with `.git`.

1	The command to create a copy locally is `clone`. Generally a shared repository is suffixed with a `.git` extension. The cloned directory is missing said suffix.
2	To place the clone into a directory not named `remote-repo` append the name of the desired destination. e.g. `git clone remote-repo.git local-repo`.

1	Compared to the initial configuration in the local repository there is new the `remote.origin.url` values pointing to the shared repository’s URL. This can be a `file` resource like in this case, `http`, `ssh` or `git`.
2	Configures the mapping between the local and remote repository when `git fetch` is issued.
3	Sets the branch master for remote in this case it is called `origin`.
4	Sets the merge branch when pulling from a repository.

1	Create a new file called `first_file.txt`.
2	Add the file to the staging area.
3	Commit the file to repository. Note at this stage nothing has been submitted to the remote repository.

1	How come there are 3 objects for one commit? Actually there is the commit object, the tree object and the blob one.
2	The actual network operation of sending the data to the shared repository.
3	Where did it send the objects to this is by default `origin`.
4	Actions done are displayed in square brackets in this case `[new branch]`. Also which branches are involved per default this is `master` for a new repository.

1	Fetch is downlowding the missing objects from remote into the object store.
2	The remote branch `master` is put into `origin/master`.

1	At this point `second_file.txt` is not appearing in the current branch `master`.
2	If the repository has been fetched why does the master branch still show the initial commit? Because fetch downloads all the objects from the shared repository and updated the `HEAD` for `origin/master` but does not merge into the local repository. This is best shown with an example.

1	Instead of simply showing the log of the current branch `git log` is instructed to display from branch `origin/master`.
2	With a decorated log one can see the head of `origin/master` is one commit ahead of the current branch.
3	Current branch HEAD points to the initial commit.

1	The `merge` command expects a source where to merge from. In this case the remote branch `origin/master` is used.
2	The messages displayed during the merge are resembling the ones from the commit.
3	Now `HEAD` and `origin/master` are in sync.

1	Section one is the same as with `git fetch`.
2	The second part is verbatim to `git merge`.

1	Adding a new line to the tracked file `first_file.txt` by appending it on the command line. Alternative one can edit the file interactively with a text editor.
2	Confirming the content has been added with `cat`.
3	Invoking `git diff` shows the changes in diff format. To explain the format at length is not in scope of this tutorial. The important syntax is that a `+` in front of a line means and addition and a `-` is a deletion.

1	Adding the previously changed file to the stating area.
2	Invoking the `git diff` shows no further changes are in the working directory.
3	To show the changes in staging the `--cached` option is passed. The result from diff is now identical as in the previous example.

1	Committing the files in stage.
2	Invoking `git diff` using the `HEAD~1` meaning show a diff between the `HEAD` and commit prior to `HEAD`. This is nearly identical to `git show` with the exception that the commit message is not shown.

1	The first line in this example is also the initial commit of the repository and demarcate the boundary of the `blame`. Boundaries prefix the SHA1 a caret symbol `^`. For brevity the SHA1 hashes are cut at character 8. With option `-l` the whole hash is shown. The tabular output format provides the following fields: `<revision hash> (<commiter name> <timestamp> <line number>) content`
2	Line two is a revision by a certain `Linux Torvalds` adding a single line to the file.
3	Line 3 is also by a different committer called `Junio C Hamano`, this time the change adds 3 lines.
4	Depicts a change not yet commited. Of note here is the SHA1 with all zeros and the committer name of `Not Commited Yet` the time stamp is the time at command execution.

1	To note here is the first line is folded into the staring commit `2e97d380` although in the previous example it was an independent commit. The caret symbol `^` demarcate the boundary of such folded commits.
2	In this example the only change made is the addition of the 3 lines by committer `Junio C Hamano`.
3	The keen observer the question is where are the lines not yet commited. When inspecting changes between specific commits unstaged changes are not factored in.

1	The first line here is the fist commit given as an option on the command line.
2	Line two is the revision provided as the end point for the comparison.

1	While the output is identical to the previous example the boundary for comparison is now the initial commit.
2	Line two is the revision provided as the end point for the comparision.

1	The comparison starts at line 2 and since the revision boundary is outside of the limit no caret symbol is shown. Of note is also the line numbers are absolute.
2	Although the commit `e5149955` spans 3 lines only the range defined on the command line is displayed.

1	Creating a copy of the existing text file with the extension `.copy`
2	Adding the newly created file to the staging area.
3	Executing the same command two result show up. Both commited changes and the ones in the staging area.
4	To limit the search to only files ending in `.txt` the shell escaped wildcards is used `'*.txt'`.
5	The result then only shows file matching the wildcard.

1	Creating a new yet to be tracked file with content.
2	Adding the `--untracked` switch to the `git grep` query includes all file under the git tree.
3	Result now also includes the untracked files. There is however no visible queue for untracked files.

1	One can also append the switch `-l` or `--list` but the output stays the same.
2	Tags are listed without any further information such as to which revision it points. The name of the tags are arbitrary alpha numerical characters. But for version releases a lowercase `v` followed by the version number is a widely followed convention.

1	Creates an annotated tag named `milestone_1` with a message.
2	With the `show` command and argument `milestone_1` the tag plus the referred commit is shown.
3	Displays the content of the tag object.
4	Message provided during tag creation.
5	The commit referred to by the tag.

1	Issuing `git push --tags` pushes only tags to the remote repository.
2	Standard push message.
3	Pushed tags are listed one per line in a tabular format.

1	During branch creation the `HEAD` of currently active branch is used as initial pointer.
2	`master` is still the current branch. The previous command only created the new branch but did not switch to it.
3	Using the checkout command we move the `HEAD` to branch `testing`
4	Not `testing` is the current working branch visible by the prefixed asterisk `*`.

1	Working under branch `testing` a new file is created.
2	File is added and commited. Noteworthy, there is no visual hint from the commit command that this is branch testing.

1	Create a new branch called `bugfix`
2	Branch `bugfix` is now the `HEAD`.