Lore

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Git Cheat-Sheet ======

A lot of this info was collected from the following sources as I used them myself to learn Git.

  * https://git-scm.com/doc - Comprehensive and well organized documentation.
  * https://githowto.com - A hands-on tutorial that is a wonderful learning tool for beginners.
  * https://www.atlassian.com/git/tutorials - More great tutorials here.
  * https://help.github.com - GitHub documentation.
  * https://guides.github.com/features/mastering-markdown - Markdown reference.

I was using ''git version 2.16.2.windows.1'' in the //Bash// shell while documenting and testing these commands.

===== First Time Configuration =====

After installing //Git// on a new system, there are a few things that should be setup first.

For further configuration options, see the [[https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration| Git documentation]].

==== Contact Info for Commits ====

<code bash>
git config --global user.name "First Last"
git config --global user.email "email@domain.com"
</code>

==== Handling Line Endings ====

<code bash>
# For Windows
git config --global core.autocrlf true
git config --global core.safecrlf true
# For Mac/Unix
git config --global core.autocrlf input
git config --global core.safecrlf true
</code>

A complementary setting in //Visual Studio Code// when developing on Windows is to enforce CRLF.

<code css settings.json>
{
    // this assumes Windows dev environment with Git config option "core.autocrlf=true"
    "files.eol": "\r\n"
}
</code>
==== Pretty Log Alias ====

More helpful aliases are demonstrated [[https://githowto.com/aliases|here]].

This log command will give nice and pretty output:

<code bash>
git log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short
# or without pagination
git --no-pager log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short
</code>

It can be configured in to a global alias like so:

<code bash>
git config --global alias.hist "log --pretty=format:'%h %ad | %s%d [%an]' --graph --date=short"
# unfortunately these won't work...
git config --global alias.hist "--no-pager log --pretty=format:'%h %ad | %s%d [%an]' --graph --date=short"
git config --global alias.hist "!git --no-pager log --pretty=format:'%h %ad | %s%d [%an]' --graph --date=short"
# but, this will disable pagination for all calls to 'log'
git config --global pager.log false

# I've recently discovered some prettier log outputs, so my .gitconfig aliases are like so...
hist = log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold cyan)%aD%C(reset) %C(bold green)(%ar)%C(reset)%C(bold yellow)%d%C(reset)%n''          %C(white)%s%C(reset) %C(dim white)- %an%C(reset)'
hist1 = log --graph --abbrev-commit --decorate --format=format:'%C(bold blue)%h%C(reset) - %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) %C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)'
hist2 = log --pretty=format:'%h %ad | %s%d [%an]' --graph --date=short
# first two are courtesy of https://stackoverflow.com/a/9074343
</code>

So now it's simply enough to do:

<code bash>
git hist
# or for all branches
git hist --all
</code>

==== VSCode as Editor and Diff Tool ====

More info [[https://code.visualstudio.com/docs/editor/versioncontrol|here]] about //Git// integration with //Visual Studio Code//.

Set //Visual Studio Code// as the default //Git// editor, and configure it to wait for the editor to close before continuing:

<code bash>
git config --global core.editor "code --wait"
</code>

Now it's possible to edit the //Git// config in //Visual Studio Code// like so:

<code bash>
git config --global -e
</code>

Leveraging the above, add the following to ''.gitconfig'':

<code>
[diff]
    tool = default-difftool
[difftool "default-difftool"]
    cmd = code --wait --diff $LOCAL $REMOTE
</code>

===== Review Git Configuration =====

<code bash>
# show all configuration settings
git config -l
# show global settings only
# these live in the user profile
git config --global -l
# show system settings only
# these live in the git installation path
git config --system -l
# show local settings only
# these live in the repo
git config --local -l
</code>

===== Create and Clone Repos =====

A **repo** is created with ''git init'', and cloned with ''git clone''.

Create a **repo** in the current folder:

<code bash>
git init
</code>

Create a **repo** in the folder ''MyRepo''(folder will be created if it doesn't exist):

<code bash>
git init MyRepo
</code>

From the parent folder, it's possible to clone a **repo** with:

<code bash>
git clone <origin> <dest>
# ex:
git clone MyRepo cloned_MyRepo
</code>

NOTE: A cloned **repo** will have a single ''master'' **branch** and remote **branches** tracked from the origin **repo**.

==== Bare Repos ====

Doing ''git init'' or ''git clone'' commands with the ''--bare'' switch will make a **repo** without a working directory, only //Git// data. A **bare repo** is intended for sharing (fetch/push/pull) only.

It's common for **bare repos** to have the suffix ''.git''.

<code bash>
# create a new bare repo in current folder
git init --bare
# create a new bare repo in folder MyRepo.git
git init --bare MyRepo.git
# clone repo MyRepo into a bare repo MyRepo.git
git clone --bare MyRepo MyRepo.git
</code>

===== Multiple Repos =====

==== Syncing ====

Commits are pulled down from a remote **repo** via ''git fetch'', however this doesn't automatically merge them in to the local **branches**.

<code bash>
# ex:
git fetch
# review status
git hist --all
</code>

However, [[#merging]] remote fetched commits is the same as any other commits. This will merge all the commits from ''origin/master'' in to the currently checked out **branch**:

<code bash>
git merge origin/master
</code>

It's possible to effectively perform ''git fetch'' and ''git merge'' in a single command via ''git pull''.

<code bash>
# fetch and merge origin/master in to current branch
git pull
</code>

Sending changes upstream to a remote **repo** is done via ''git push''.

<code bash>
# push to <remoterepo> local <branch>
git push <remoterepo> <branch>
# ex:
git push origin master
# push everything
git push --all
</code>

If, as mentioned in [[#managing remote repos]], local **branches** are already configured to track remote **branches**, it shouldn't be necessary to specify any parameters. Simply running ''git push'' should be enough.

==== Tracking Branches ====

When a **repo** is cloned, the only local **branch** is ''master'', and while the other remote **branches** are tracked, ''git pull'' and ''git push'' are only setup between the local and remote ''master'' **branches**. This can be confirmed by reviewing the remote configuration.

<code bash>
# check configured remote repos
git remote
# show details for a configured remote repo
git remote show <repo>
# ex:
git remote show origin
</code>

It is possible to create a local **branch** that tracks commits from a remote **branch**:

<code bash>
# create a new localbranch to track remotebranch
git branch --track <localbranch> <remotebranch>
# ex:
git branch --track dev1 origin/dev1
</code>

It is also possible to modify an existing local **branch** and set it to track commits from a remote **branch**:

<code bash>
# for currently checked out branch
git branch -u <remotebranch>
# ex:
git branch -u origin/dev1
# for NOT currently checked out branch
git branch -u <remotebranch> <localbranch>
# ex:
git branch -u origin/dev1 dev1
</code>

NOTE: After using ''git branch -u'' the local **branch** will display as ''fast-forwardable'' via ''git remote show origin''. To clear this up, simply force a ''git push'':

<code bash>
# push all refs
git push --all
</code>

==== Managing Remote Repos ====

<code bash>
# add a remote repo
git remote add <reponame> <repopath>
# ex:
git remote add origin ../folder
# remove remote repo
git remote rm <reponame>
# ex:
git remote rm origin
</code>

With ''git push -u'' it's possible accomplish the same things as ''git branch -u'', the latter being more specific in how to link **branches**.

<code bash>
# configure branchname to track remote branchname on reponame
git push -u <reponame> <localbranch>
# ex:
git push -u origin master
git push -u origin dev1
# alternatively, this will do above for all branches
git push -u --all
</code>

When a **repo** is cloned, remote ''HEAD'' tracking is configured automatically. When setting up remote **repos** manually it's possible to do this with ''git remote set-head''.

<code bash>
# set reponame/HEAD as master
git remote set-head <reponame> -a
# ex:
git remote set-head origin -a
# remove reponame/HEAD as master
git remote set-head <reponame> -d
# ex:
git remote set-head origin -d
</code>

In some cases it may be desired to disable ''git push'' and effectively setup a pull only **repo**. There is no official disable switch, but it's possible to provide a bogus URL that will generate an error.

<code bash>
# set the remoterepo push url
git remote set-url --push <remoterepo> <url>
# ex:
git remote set-url --push origin DISABLE
</code>

To track certain remote **branches** use ''git remote set-branches''. Using the ''--add'' switch will append the current configuration, otherwise it will be replaced.

<code bash>
# track only <remoterepo> <remotebranch>
git remote set-branches <remoterepo> <remotebranch>
# ex:
git remote set-branches origin master
# whoops, also want to track dev1 branch
git remote set-branches --add origin dev1
</code>

When a tag is removed from the local **repo** it will not be removed from the remote **repo** via standard ''git push'' or even ''git push --all'', but there is a way to do it.

<code bash>
# delete <tag> from <remoterepo>
git push <remoterepo> :<tag>
# ex:
git push origin :v1.0
</code>

Alternatively, if new tags were created but there are no new commits, it's possible to push the tags to the remote **repo** via ''git push --tags''.

===== Stage, Confirm, Commit, and Tag =====

Note: Before the initial commit occurs on a new **repo**, the ''master'' **branch** doesn't exist yet, and many commands will throw errors.

Stage files:

<code bash>
# a single file
git add file.txt
# multiple via wildcard
git add *.txt
# all via shell wildcard
# - will ignore what shell ignores, like .folders
git add *
# all via git wildcard
# - will pull in everything that isn't in .gitignore
git add .
</code>

Confirm **repo** status:

<code bash>
git status
</code>

Commit changes:

<code bash>
# commit and launch default editor to provide comment
git commit
# commit and provide comment in-line
git commit -m "Commit comment"
</code>

To correct a mistake in the last commit:
  * Make the necessary changes
  * Stage the necessary files
  * Perform a new commit with the ''--amend'' switch

<code bash>
git commit --amend -m "Commit comment"
</code>

Tag commits for easier management:

<code bash>
# tag the current commit with a friendly name
git tag <name>
# ex:
git tag v1
# tag the previous commit using '^' notation
git checkout v1^
git tag v0
git checkout v1
# remove tag
git tag -d v1
</code>

===== Undo Changes =====

Unstaged changes can be rolled back via ''git checkout''.

<code bash>
# checkout a single file
git checkout file.txt
# checkout all files
git checkout .
</code>

This is not an undo, but instead of checking out files, it's possible to checkout a commit via the first 7 digits of the hash (from ''git hist'' if the [[#set alias for pretty log output|alias]] is defined), or tags:

<code bash>
git checkout <hash>
# ex:
git checkout 9b2c81a
</code>

To return to the latest commit do:

<code bash>
git checkout <branch>
# ex:
git checkout master
</code>

Staged changes can be rolled back via ''git reset''.

<code bash>
# unstage all currently staged changes
git reset
# unstage a particular file
git reset HEAD <file>
# ex:
git reset HEAD file.txt
</code>

NOTE: The working directory still has modified and unstaged files, use ''git checkout'' to replace them with committed version:

<code bash>
git checkout .
# or, for a single single file
git checkout file.txt
</code>

Commits can be canceled (but not removed) via ''git revert''. Cancel commits by targeting their hash, or other identifiers.

This will cancel wherever ''HEAD'' is, which is usually the last commit:

<code bash>
git revert HEAD
</code>

Commits can be removed from history via ''git reset''.

To revert the working directory to a specified commit, and remove all later commits from history:

<code bash>
git reset --hard <hash>
# ex:
git reset --hard e54ff04
</code>

NOTE: If removed commits had tags, those tags need to be removed or the commits will remain in history. This can be done after ''git reset'':

<code bash>
git tag -d BadVersion
</code>

===== Moving Content =====

Content can be moved inside the **repo** via ''git mv'', this is the best option when moving a single file, although more files just mean repeating the command for them.

<code bash>
# files and/or folders can be moved like this
git mv <source> <dest>
# ex:
git mv file.txt folder\file.txt
git mv folder1 folder2
# it's better to use 'git mv' instead of native file system
# to avoid more steps:
mv file.txt lib
git add folder/file.txt
git rm file.txt
</code>

If using the file system to move content around, especially serious restructuring, it's a better idea to use ''git add -A''.

<code bash>
# update the entire worktree
git add -A
# update current folder and down
git add -A .
# update a specific folder
git add -A MyFolder
</code>

===== Branches =====

Branches are managed via ''git branch'', switched via ''git checkout'', and merged via ''git merge''.

==== Create, List, Checkout, and Delete ====

<code bash>
# list branches
git branch
# create a new branch
git branch <name>
# ex:
git branch dev1
# list local branches
git branch
# list all branches
git branch -a
# switch working directory to branch dev1
git checkout dev1
# it's possible to create a new branch and checkout in one command
git checkout -b dev2
# to delete a branch (can't be checked out)
git branch -d dev1
</code>

==== Merging ====

<code bash>
# merge <branch> in to the currently checked out branch
git merge <branch>
# ex: # this brings all the changes from dev1 in to master
git checkout master
git merge dev1
</code>

==== Rebasing ====

Branches can be rebased with ''git rebase''. Rebasing merges the **branch** histories in to a single thread, effectively performing a merge and then flattening the commit tree.

<code bash>
# rebase the currently checked out branch in to <branch>
git rebase <branch>
# ex: # this flattens the dev1 history in to master
git checkout dev1
git rebase master
</code>

NOTE: Rebasing can get tricky in some scenarios and cause issues, check the documentation for further details:

<code bash>
git rebase --help
</code>

===== Ignoring Content =====

It's possible to tell //Git// to ignore files and/or folders by using a ''.gitignore'' file.

See the following for more details and examples:
  * https://git-scm.com/docs/gitignore - official documentation.
  * https://www.gitignore.io - great tool for getting a quick and simple starting template.
  * https://www.atlassian.com/git/tutorials/saving-changes/gitignore - more examples here.
  * https://jasonstitt.com/gitignore-whitelisting-patterns - a helpful blog post.

<code git .gitignore>
# matching is done on the whole path string, so
# this will ignore everything regardless of depth
*
# whatever exceptions are made, will only work in
# the current folder, unless recursion is allowed with
!*/
# this will whitelist at the top level
!*.ps1
# this will whitelist everywhere
!**/*.xml
# lines are processed in order, so it's possible
# to undo everything above with
!*
</code>

==== PowerShell Visual Studio Code Template ====

This is my baseline template for starting a //PowerShell// project in //Visual Studio Code//. It's effectively a white-list.

<code git .gitignore>
# ignore everything eveywhere
*

# allow folder recursion
!*/

# allow .git* at top level
!.git*

# allow .md at top level
!*.md

# whitelist VSCode settings at the top level
!/.vscode/settings.json

# whitelist contents of these folders at the top level
!/ProjectFolderContainingAllTheGoodies/**

# regardless of above, ignore these folders and files everywhere
**/_logs*
**/_testing*

</code>

Here is a template generated by [[https://www.gitignore.io|gitignore.io]] for //PowerShell//, //Visual Studio Code//, and //Windows//.

<code git .gitignore>
# Created by https://www.gitignore.io/api/windows,powershell,visualstudiocode

### PowerShell ###
# Exclude packaged modules
*.zip

# Exclude .NET assemblies from source
*.dll

### VisualStudioCode ###
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
.history

### Windows ###
# Windows thumbnail cache files
Thumbs.db
ehthumbs.db
ehthumbs_vista.db

# Folder config file
Desktop.ini

# Recycle Bin used on file shares
$RECYCLE.BIN/

# Windows Installer files
*.cab
*.msi
*.msm
*.msp

# Windows shortcuts
*.lnk

# End of https://www.gitignore.io/api/windows,powershell,visualstudiocode
</code>

{{tag>computing git}}