On Git

References

• Git Documentation

• Git Reference
  • Git configuration variables
  • Revisions
  • gitignore Pattern Format
• Pro Git
  • Git References
  • Git Branching
  • Remote Branches
• GitHub Bootcamp
  • As of Nov. 1st 2012, one important thing is missing. That is sharing the project in Eclipse, after cloning the fork in the server. Maybe it could be a defect of Eclipse, not a miss of the article.
• Git Cheatsheet
  • Workspace
  • Local Repository
  • Upstream Repository
• Git Tutorials by Bitbucket
• Git Workflows
• EGit User Guide
  • Git References(Refs)
  • Remotes

Commands

category	command	description	remark
Setup	git config	Get and set repository or global options	git config --get core.autocrlf git config core.autocrlf false
Creating	git clone	Clone a repository into a new directory
	git init	Create an empty Git repository or reinitialize an existing one
Basic	git add
	git status	Show the working tree status
	git diff	Show changes between commits, commit and working tree, etc
	git commit
	git reset	Reset current HEAD to the specified state
	git reset --hard	Resets the index and working tree. Any changes to tracked files in the working tree since commit are discarded.
	git restore	Restore working tree files
	git rm	Remove files from the working tree and from the index
	git rm -rf --cached	Only remove from the index	Working tree files, whether modified or not, will be left alone
Branching	git branch	List, create, or delete branches
	git branch --list	List branches.	-l
	git branch --all	List both remote-tracking branches and local branches.	-a
	git branch --move	Move/rename a branch and the corresponding reflog.	-m
	git branch --delete	Delete a branch.	-d
	git checkout	Switch branches or restore working tree files
	git log	Show commit logs	git log master -3
	git tag	Create, list, delete or verify a tag object signed with GPG
	git tag -a	Make(create) an unsigned, annotated tag object	--annotate
	git tag --delete	Delete existing tags with the given names.	-d
Sharing	git pull
	git push
	git push --all	Push all branches (i.e. refs under refs/heads/)
	git push --tags	All refs under refs/tags are pushed
	git push --follow-tags
	git push --set-upstream	For every branch that is up to date or successfully pushed, add upstream (tracking) reference, used by argument-less git-pull and other commands.
	git remote	Manage set of tracked repositories
Patching	git rebase	Reapply commits on top of another base tip
	git revert	Revert some existing commits	Requires your working tree to be clean (no modifications from the HEAD commit)
Administration	git clean	Remove untracked files from the working tree
	git archive	Create an archive of files from a named tree	git archive -o latest.zip HEAD
Plumbing	git ls-files	Show information about files in the index and the working tree	git ls-files | wc -l
	git show-ref	List references in a local repository
Guides	gitignore		($HOME/.config/git/ignore, $GIT_DIR/info/exclude, .gitignore)
Misc	git svn	Bidirectional operation between a Subversion repository and Git

Refs

• Git References(Refs)
• Git Internals - Git References

Type	Format	Example	Remarks
Local branches	refs/heads/...	refs/heads/2.x, refs/heads/3.x
Remote tracking branches	refs/remotes/...	refs/remotes/origin/master, refs/remotes/upstream/master
Tags	refs/tags/...	refs/tags/v0.9, refs/tags/v1.5.RELEASE, refs/tags/v2.0.GA

           +--- HEAD
           |
           +--- FETCH_HEAD
           |
           +--- ORIG_HEAD
           |
  .git/ ---+--- refs/ ---+--- heads/ ---+--- master
                         |              |
                         |              +--- next
                         |
                         +--- tags/ ----+--- v0.9
                         |              |
                         |              +--- v1.0
                         |              |
                         |              +--- v1.1
                         |
                         +--- remotes/ ---+--- origin/ --- master
                                          |
                                          +--- upstream/ --- master

Reserved Refs

Reserved	Full	Description
master	refs/heads/master	local master branch
origin/master	refs/remotes/origin/master
v1.0.1	refs/tags/v1.0.1
HEAD		currently checkout commit
FETCH_HEAD		the result of the last fetch operation
ORIG_HEAD		the commit that was checked out before a merge or rebase operation was started

HEAD

• The HEAD

$ cat .git/HEAD
ref: refs/heads/master
$ git checkout test
...
$ cat .git/HEAD
ref: refs/heads/test

Configuration

• Git configuration variables

Variable	Data Type	Description	Default	Remarks
push.followTags	boolean	If set to true enable --follow-tags option by default.	false	--no-follow-tags

Model

• Git Cheatsheet
• Git Workflow

File State-chart

  Untracked           Modified            Staged        Committed
      |                  |                 |               |
      +- add ------------|---------------->|               |
      |                  |                 |               |
      |                  +- add ---------->|               |
      |                  |                 |               |
      |                  |                 +- commit ----->|
      |                  |                 |               |
      |                  |                 |               |
      |                  |<----------------|-------- edit -+
      |                  |                 |               |
      |<-----------------+-----------------+------ remove -|
      |                  |                 |               |


                       * Tracked = Modified | Staged | Committed

                            
  +-----------+            +---------+            +------------+
  | Untracked | ---add---> | Staged  | <---add--- | Modified   |
  |(workspace)|            | (index) |            |(workspace)|
  +-----------+            +---------+            +------------+
                                |                      ^
                                |                      |
                             commit                  edit
                                |                      |
                                |     +-----------+    |
                                +---> | Committed | ---+
                                      +-----------+

Areas

Area	Role	Description	Remarks
Workspace	Working directory	Consists of files that you are currently working on.	Local checkout
Index	Staging area, Cache	Where commits are prepared.
Stash		A place to hide modifications while you work on something else
Local Repository
Upstream Repository

Branching

$ git commit -a -m "..."

                         << master, HEAD >>
                                  |  
    +----+        +----+        +----+
    | c1 | <----- | c2 | <----- | c3 | 
    +----+        +----+        +----+

$ git branch iss31  # branch to work on issue 31 - new feature

                         << master, HEAD >>
                                  |  
    +----+        +----+        +----+
    | c1 | <----- | c2 | <----- | c3 | 
    +----+        +----+        +----+
                                  |
                             << iss31 >>

$ git checkout iss31

                             << master >>
                                  |  
    +----+        +----+        +----+
    | c1 | <----- | c2 | <----- | c3 | 
    +----+        +----+        +----+
                                  |
                          << iss31, HEAD >>

$ # edits or adds some files
$ git commit -a -m ...

                             << master >>
                                  |  
    +----+        +----+        +----+        +----+
    | c1 | <----- | c2 | <----- | c3 | <----- | c4 |
    +----+        +----+        +----+        +----+
                                                |
                                        << iss31, HEAD >>

$ # a simple bug is found, create anothter branch for hotfix on 'master' 
$ git checkout master
$ git checkout -b hotfix  # same with 'git branch hotfix; git checkout hotfix'
 
                         << master, HEAD >>
                                  |  
    +----+        +----+        +----+        +----+
    | c1 | <----- | c2 | <----- | c3 | <----- | c4 |
    +----+        +----+        +----+        +----+
                                                |
                                           << iss31 >>

                          << hotfix, HEAD >> 
                             << master >>
                                  |  
    +----+        +----+        +----+        +----+
    | c1 | <----- | c2 | <----- | c3 | <----- | c4 |
    +----+        +----+        +----+        +----+
                                                |
                                           << iss31 >>

$ # edits some files to fix the bug
$ git commit -a -m ...

                                           << hotfix, HEAD >>
                                                   |
                                                 +----+
                              << master >>   +-- | c5 |
                                   |         |   +----+
    +----+        +----+        +----+ <-----+
    | c1 | <----- | c2 | <----- | c3 | 
    +----+        +----+        +----+ <-----+ 
                                             |   +----+ 
                                             +-- | c4 |
                                                 +----+
                                                   |
                                              << iss31 >>

$ # after successful testing on hotfix, merge 'hotfix' to 'master'. remove 'hotfix' after merge
$ git checkout master
$ git merge hotfix   # 'master' fast-forwarded
$ git branch --delete hotfix   # --delete == -d

                                              << hotfix >>
                                          << master, HEAD >>
                                                   |
                                                 +----+
                                             +-- | c5 |
                                             |   +----+
    +----+        +----+        +----+ <-----+
    | c1 | <----- | c2 | <----- | c3 | 
    +----+        +----+        +----+ <-----+ 
                                             |   +----+ 
                                             +-- | c4 |
                                                 +----+
                                                   |
                                              << iss31 >>

                                          << master, HEAD >>
                                                   |
                                                 +----+
                                             +-- | c5 |
                                             |   +----+
    +----+        +----+        +----+ <-----+
    | c1 | <----- | c2 | <----- | c3 | 
    +----+        +----+        +----+ <-----+ 
                                             |   +----+ 
                                             +-- | c4 |
                                                 +----+
                                                   |
                                              << iss31 >>

$ # after hotfix, works on 'iss31' branch with other commits
$ git checkout iss31

                                              << master >>
                                                   |
                                                 +----+
                                             +-- | c5 |
                                             |   +----+
    +----+        +----+        +----+ <-----+
    | c1 | <----- | c2 | <----- | c3 | 
    +----+        +----+        +----+ <-----+ 
                                             |   +----+      +----+      +----+  
                                             +-- | c4 | <--- | c6 | <--- | c7 | 
                                                 +----+      +----+      +----+
                                                                           |
                                                                   << iss31, HEAD >>

$ # when 'iss31' implemented successfully
$ git checkout mater
$ git merge iss31   # if no conflict, simple three-way merge with another new commit

                                                                                  << master, HEAD >>
                                                                                           |
                                                 +----+ <------------------------------- +----+
                                             +-- | c5 |                                  | c8 |
                                             |   +----+                           +----- +----+
    +----+        +----+        +----+ <-----+                                    |        |
    | c1 | <----- | c2 | <----- | c3 |                                            |   << iss31 >>
    +----+        +----+        +----+ <-----+                                    | 
                                             |   +----+      +----+      +----+   |
                                             +-- | c4 | <--- | c6 | <--- | c7 | --+
                                                 +----+      +----+      +----+

Commands

merge	A---B---C topic / D---E---F---G master	git merge topic	A---B---C topic / \ D---E---F---G---H master
rebase	A---B---C topic / D---E---F---G master	git rebase master topic	A'--B'--C' topic / D---E---F---G master
	A---B---C topic / D---E---A'---F master	git rebase master topic	B'---C' topic / D---E---A'---F master

Readings

• What's a “fast-forward” in Git?
• Is there any way to clone a git repository's sub-directory only?
• How to change file premissions in Git on Windows (Nov. 2011)
• Git - Get Current Working Copy Version (Jan 23 '12)
  • git log -1
• How to get latest git commit hash command (Mar 28 '13)
• Dealing with line endings
• What does tree-ish mean in Git?(Oct 28 '10)
• Ignoring files
• gitignore: Ignore all files in folder hierarchy except one specific filetype (Oct 18 '11)
• How do negated patterns work in .gitignore? (May 12 '10)
  • /excluded/*, !/excluded/included
• Git v2.0.0, what changed, and why should you care (2014/05/29)
• Adding an existing project to GitHub using the command line

Revision

• What is a Git Revision Expression? (Aug 1 '09)
• Revision Selection
• gitrevisions
• Git References : refs/heads/, refs/remotes/, refs/tags/ ...
• <refname>
• What is the parent of a git commit? How can there be more than one parent to a git commit? (Jul 7 '16)

Basic Snapshotting

add, status, diff, commit, restore, reset

status

• Recording Changes to the Repository
• Difference between untracked, unstaged and staged changes

diff

• How to diff the same file between two different commits on the same branch? (Jul 26 '10)
• Git diff between given two tags (Jul 9 '10)
• git: diff between file in local repo and origin (Jan 13 '14)
  • $ git fetch; git diff --summary master origin/master

reset

• Reset, restore and revert

command	Description	Remark
restore	about restoring files in the working tree from either the index or another commit.	does not update your branch
reset	updating your branch, moving the tip in order to add or remove commits from the branch.	can also be used to restore the index, overlapping with git restore.
revert	about making a new commit that reverts the changes made by other commits.

git revert is used to record some new commits to reverse the effect of some earlier commits (often only a faulty one). If you want to throw away all uncommitted changes in your working directory, you should see git-reset, particularly the --hard option. If you want to extract specific files as they were in another commit, you should see git-restore, specifically the --source option. Take care with these alternatives as both will discard uncommitted changes in your working directory.

rm

• Git treats folder as file and ignores all subfolders and -files (Nov 15 '16)

Branching

branch, checkout, switch, merge, log, tag

branch

• A branch in Git is simply a lightweight movable pointer to one of these commits.
• Every time you commit, the master branch pointer moves forward automatically.
• HEAD is a pointer to the local branch you’re currently on.

Term	Description	Remark
Remote-tracking Branch
Upstream Branch

• What is the difference between origin and upstream on GitHub? (Feb 13 '12)
• Definition of “downstream” and “upstream”(Apr 29 '10)
• Removing a remote
• How do you create a remote Git branch? (Oct 5 '09)
  • git push <remote-name> <local-branch-name>:<remote-branch-name>
• How To Rename a Local and Remote Git Branch (Feb 18, 2020)
  • git branch -m name, git push origin --delete name
• How to list all the files in a commit? (Jan 8 '09)
  • git show --name-only -1, git log --name-only -1

checkout

• How to checkout remote git tag (Mar 14 '16)
  • git checkout v1.0.0, git checkout tags/v1.0.0
• How to get back to most recent version in Git? (Aug 24 '10)
  • git checkout master

• Git tip: How to "merge" specific files from another branch (February 25, 2009)
  • git checkout source_branch paths

tag

• How to push a tag to a remote repository using Git? (Mar 4 '11)
  • git push origin --tags
• How to list all tags along with the full message in git? (Mar 18 '11)
  • git tag -l -n9
• How do you push a tag to a remote repository using Git? (Mar 4 '11)
  • git push origin <tag_name>

Sharing

fetch, pull, push, remote

• Find out which remote branch a local branch is tracking (Oct 5 '08)
  • git branch -vv, git status
• Pushing to a remote
  • By default, and without additional parameters, git push sends all matching branches that have the same names as remote branches.

Workflow

• Comparing Workflows
• Git Feature Branch Workflow
• Gitflow Workflow
• Forking Workflow

• A successful Git branching model (January 05, 2010)

Hooks

• Git Hooks

Tools

• Interfaces, frontends, and tools

Misc

• Changing a commit message : git commit --amend
• Add line break to 'git commit -m' from the command line (Feb 21 '11)

Subtree

• About Git subtree merges
  • to manage multiple projects within a single repository
• Mastering Git subtrees

Typical Usage

List all configuration

$ git config --list --show-scope --show-origin

Adding new items, committing and pushing them

$ git status .                    // identifies added, modified or untracked items under current local directory
$ git add .                       // updates index
$ git status .                    // confirms the changes to be committed
$ git commit -m "message ..."     // commits changes into local repository
$ git status .                    // confirms all changes are committed
$ git push                        // pushes changes in local repository onto the remote repository
$ git log --name-only -1         // lists files in the last commit

When the HEAD of 'origin/master' has changed since the last sync, '$ git push' would fail with messages including fast-forwards. Then,

$ git pull --rebase
...
may need manual merge.
...
$ git push

Working with remote repositories

$ git remote -v          // lists tracking repositories
$ git remote add upstream https://github.com/jpmorganchase/quorum.git     // add a new remote repository to track
$ git branch -r          // lists branches in tracking repositories

Working with branches or tags

$ git tag -ln                                // lists tags
$ git tag -a v2.0.2 -m "before new branch"   // creates a new annotated tag(v2.0.2)
$ git tag origin v2.0.2                      // push a tag to a remote 
$ git push origin --tags                     // pushes all local tags to remote 'origin'

$ git branch                                 // lists branches
$ git branch -a                              // lists both local and remote-tracking branches
$ git branch -avv                            // lists all branches showing hash and upstream branch if any

$ git branch 1.1                             // creates a new branch(1.1) from the master (branch)
$ git branch 2.0.2-ext v2.0.2                // creates a new branch(2.0.2-ext) from a tag(v2.0.2)
$ git push origin advanced:advanced          // creates remote branch 'origin/advanced' from local branch 'advanced'
$ git push --set-upstream origin advanced    // sets upstream(tracking) reference for current branch to 

$ git checkout release-1.1                   // updates working tree to release-1.1
$ git checkout -b gh-pages origin/gh-pages   // copies remote branch to local repository

Tracking changes

$ git log master -3                          // lists 3 recent commits for master branch
$ git log v2.0.2 -3                          // lists 3 last commits before the tag of 'v2.0.2'
$ git log origin/master -1                   // lists last commit of remote branch 'origin/master'
$ git log upstream/master -1                 // lists last commit of remote branch 'upstream/master'
$ git log --name-only -1                    // lists files in the last commit.

Undoing

Use-case	Solution	Remarks
Removing untracked files and directories	git clean -dx
Removing uncommitted changes on all the tracked files	git reset --hard
Removing uncommitted changes on a single or selected tracked files
Removing committed changes	git revert

Removing untracked files and directories in the working tree

$ git clean -ndx          // -n: dry run, -d: directory also, -x: skip gitignore
...
$ git clean -ffdx         // -ff: force including files manged by different Git repository
...

For more, refer

• how to remove untracked files in Git? (Nov 20 '11)
• How to remove local (untracked) files from the current Git working tree? (Sep 14 '08)

Undoing tracked files

• To remove uncommitted changes on tracked files in the working tree, use 'git reset --hard'.

$ git reset --hard          // resets the index and working tree. Any changes to tracked files in the working tree since <commit> are discarded.

• To unstage a staged file, use 'git reset HEAD <<file>>'.

$ git reset HEAD CONTRIBUTING.md

• To unmodify a modified file, use 'git checkout -- <<file>>'.

$ git checkout -- CONTRIBUTING.md

Removing committed changes

@TODO

Creating and pushing tag

$ git tag -a v1.0 -m "Ready to offer externally"
...
$ git push origin v1.0
...

Creating local repository using existing artifacts and pushing it to the remote bare repository

$ git init
$ git add .
$ git status .
$ git commit -m "..."
$ git remote add origin https://github.com/.../....git
$ git push --set-upstream origin master
$ git remote -v

Look around local repository

$ git status .          // show the working tree status
$ git branch -avv       // list both remote-tracking branches and local branches.
$ git tag -ln           // list tags
$ git remote -v         // list tracking repositories
$ git show-ref --head   // list references in a local repository 
$ git log origin/master -3  // lists 3 recent commits for remote branch 'origin/master'
$ git ls-files         // show information about files in the index and the working tree
$ git config -l        // list all variables set in config file, along with their values.

Companions

GitHub

• GitHub Help
• Searching code

• Fork A Repo
• Syncing a fork
• Configuring a remote for a fork
• Configuring Git Large File Storage : Git LFS
• Adding an existing project to GitHub using the command line

• GitHub Cheat Sheet
• GitHub Markup Support
  • The library that every markup file in a repository goes on before it is rendered on GitHub.com:

Markup	Extension	Library
Markdown	.markdown, .md	https://github.com/gjtorikian/commonmarker
MediaWiki	.mediawiki, .wiki	https://github.com/nricciar/wikicloth
Textile	.textile	https://github.com/jgarber/redcloth
AsciiDoc	.asciidoc, .adoc	http://asciidoctor.org/
reStructuredText	.rst

GitHub Pages

• GitHub Pages
• GitHub Pages Basics gh-pages
  • Creating Project Pages manually
  • User, Organization, and Project Pages
  • Setting up your GitHub Pages site locally with Jekyll
• GitHub Flavored Markdown

• Master and gh-pages in Github: keep your code and website in the same repo (Jun 14, 2015)

• Get Started With GitHub Pages (Plus Bonus Jekyll)(18 December 2013)
• A blog site with Jekyll, Github Pages Eclipse Che and Codenvy
• Using Jekyll as a static site generator with GitHub Pages
• Collapsible Code Blocks in GitHub Pages (May 2, 2019)
  • <details><summary>...</summary>``` ... ```</details>
• How I can move JavaDoc from master branch to gh-pages branch on GitHub using EGit and Eclipse? (Aug 13 '12)

• GitHub Pages supported themes
• GitHub Pages themes
  • primer, cayman, hacker, minimal, midnight

EGit

• http://www.eclipse.org/egit/
• Desc : an Eclipse Team provider for the Git version control system.
• License
• Readings
  • EGit User Guide
    • Resolving a merge conflict
  • Git For Eclipse Users
  • EGit Getting Started
  • EGit/GitHub/User Guide : explains how to use EGit Mylyn GitHub connector.
  • EGit Compare shows all lines as changed (Dec 30 '13)
    • EGit doesn't support .gitattributes file.

Gitorious

• Desc : Git hosting and collaboration software that you can install yourself
• License : GNU Affero General Public License

GitLab

• https://github.com/gitlabhq/gitlabhq
• Desc : self hosted Git management software
• License : MIT license

Gogs

• https://gogs.io/
• Desc. : a painless self-hosted Git service
• License : MIT License
• Sources : https://github.com/gogs/gogs

Tips and Tricks

Typical .gitignore

A typical .gitignore file contains

# references
#   https://git-scm.com/docs/gitignore
#   https://github.com/github/gitignore

# source version control related
CVS/
.svn/
.hg

# IDEs or tools related
/.idea/
/.vscode/
.gradle/

# directories for intermediate or final compiled artifacts
/bin/
/target/
/build/
/output/
/Debug/
/Release/
/x86/
/x64/
/obj/

# dependencies
/node_modules/*
/pkg/

# generated artifacts
/reports/
/_site/
.apt_generated/
.atp_generated_tests/

# runtime outputs
/run/
/log/
/logs/
/test-output/
*.log
npm-debug.log

# backups, caches, or temporary artifacts
.~*
._*
*.bak
.cache*
.*.swp
*.md.html
package-lock.json
Gemfile.lock
.sass-cache
__pycache__/
.pytest_cache/
packer_cache/

# misc
config.gypi
.npmrc
.jekyll-metadata
.DS_Store
.lock-wscript
.wafpickle-N

# build outputs of Remix-IDE for smart contracts - https://remix-ide.readthedocs.io/en/latest/contract_metadata.html
contracts/**/artifacts/


# don't ignore OpenZeppelin contracts
# !/node_modules/@openzeppelin
# /node_modules/@openzeppelin/*
# !/node_modules/@openzeppelin/contracts-3
# /node_modules/@openzeppelin/contracts-3/build
# /node_modules/@openzeppelin/contracts-3/package.json
# /node_modules/@openzeppelin/contracts-3/**/artifacts
# !/node_modules/@openzeppelin/contracts-4
# /node_modules/@openzeppelin/contracts-4/build
# /node_modules/@openzeppelin/contracts-4/package.json
# /node_modules/@openzeppelin/contracts-4/**/artifacts

For more, refer

• gitignore documentation
• A collection of useful .gitignore templates

Typical .gitattribute

* -text

*.tag -text
*.MF -text
*.aj -text
*.ftl -text
*.mediawiki -text
*.textile -text
*.q -text
*.g -text
*.tokens -text
*.script -text
*.cfg -text
.classpath -text
.project -text
.jsdtscope -text
*.prefs -text
*.component -text
*.launch -text
.springBeans -text
.euml2 -text
.umlproject -text
.clay -text
.fbprefs -text
.pmd -text
.lint4jprefs -text
.jshintrc -text

*.sol linguist-language=Solidity

# Declare files that will always have CRLF line endings on checkout.
*.sln text eol=crlf

# Denote all files that are truly binary and should not be modified.
*.a binary
*.o binary
*.so binary
*.lib binary
*.com binary
*.exe binary
*.dll binary
*.bin binary
*.zip binary
*.7z binary
*.png binary
*.jpeg binary
*.jpg binary
*.gif binary
*.bmp binary
*.tif binary
*.tiff binary
*.mp3 binary
*.mp4 binary
*.avi binary
*.flv binary
*.ico binary
*.class binary
*.jar binary
*.doc binary
*.docx binary
*.xls binary
*.xlsx binary
*.ppt binary
*.pptx binary
*.pdf binary