======git======
A general guide for the distributed version control system Git.

  * {{ :wiki:git-cheatsheet-en-dark.pdf | Git cheatsheet}}

This guide shows the Git commands, but for ease of use these can be wrapped in shell functions. See [[powershell_git|Powershell Git]].

===Initial Git configuration===
<code bash>
git config --global user.name "Your Name Here"
git config --global user.email your@email.com
git config --global core.excludesFile ~/.gitignore
git config --global init.defaultBranch main
</code>

Check the configuration
<code bash>
git config --list
</code>

=== Initializing or Cloning a Repo ===

Start by initializing a new repo or cloning an existing one.

===Initialize new repository ===
Since a project that is just starting tends to be rudimentary it makes sense to initially create the repo with an empty master branch and then immediately create a //working// branch where the initial work will begin. Once the project gets further along and hits certain milestones the changes can be merged into the master branch.

  * ''%%--allow-empty%%'' allows a commit to the repo without any files added.

Below is an example using Powershell to only run commands if there is not an existing Git repo configured.

**git-init.ps1**
<code powershell>
param(
    [Parameter(Mandatory=$true)] [String]$email
)

if (-not(Test-Path -Path ".\.git")) {
    git init --initial-branch=main
    git config --global user.name "John Doe"
    git config --global user.email $email
    git config --global core.excludesFile ~/.gitignore
    git commit --allow-empty -m "Initial commit for bootstrapping the repo"
    git checkout -b working
}
</code>

<code powershell>
git-init.ps1 -email "jdoe@gmail.com"
</code>

== Sample .gitignore ==
<code>
.gitignore
.vscode
*.pyc
__pycache__/
**/.working/*
</code>

  * [[git_init|Git Init]]

== Setup remote repositories for Github and the like ==
<code bash>
git remote add <remote name> <remote url>
</code>

=== Clone Existing Repo ===
<code bash>
git clone <url>
</code>

=====Typical Workflow=====
  * Clone an existing repo or initialize a new one
  * Edit some source code.
  * Stage (new, changed and deleted) the changes.
  * Commit to the local repo.
  * Fetch changes from remote repo and merge them into working files.
  * Push changes out to remote repo.

<code bash>
git diff HEAD
git add -u
git commit -m "wip"
git fetch
git merge <remote name>/<branch>
git push -u <remote name> <branch>
# Alternatively, push all branches
git push --all <remote name>
</code>

====== Seeing Changes ======
See what's new or modified in the working directory.
<code bash>
git status
</code>

List files that were part of the specified commit. Alias ''gls''
<code bash>
git ls-tree --full-tree --name-only -r $commit
</code>

Show the details, including changes made, for the specified commit.
<code bash>
 git show $commit
</code>

See the changes between the current working directory and the last commit (HEAD) or some other commit (e.g. HEAD~1).
<code bash>
git diff HEAD
</code>

  * ''git diff'': Show differences between your working directory and the index.
  * ''git diff –cached'': Show differences between the index and the most recent commit.
  * ''git diff HEAD'': Show the differences between your working directory and the most recent commit.
  * ''git diff --name-only <commit> <commit>'': Show the files that changed between two commits.

==== History ====
<code bash>
git log
</code>

====== Branches ======
  * Checkout the branch the new branch is based on
  * Then create branch
<code bash>
git branch <new branch name>
</code>
  * Create a ranch and check it out in one command
<code bash>
git checkout -b <new branch name>
</code>

=== Deleting Branches ===
  * Delete remote branch, if it exists
  * Then delete the local branch
<code bash>
git push -d <remote_name> <branch name>
git branch -d <branch name>
</code>

To force delete an unmerged branch
<code bash>
git branch -D <branch name>
</code>

====== Remotes ======
Push branch to remote repo
<code bash>
git push -u <origin name> <branch name>
</code>

====== Squashing Commits ======
To tidy up a messy trail of commits
====Squash last n commits to one====
<code>
git reset --soft HEAD~n && git commit -m 'new commit message'
git push <remote> <branch> --force
</code>

====== Archive/Dump/Extract to zip ======

<code bash>
git archive --format=zip -o $zip_file $commit [file(s) to archive]
</code>

Example wrapper function in Powershell
<code powershell>
function git-extract([Parameter(Mandatory=$true)][string]$commit, [Parameter(Mandatory=$true)][string]$path) {
    $temp_file="$env:temp\git-dump.zip"; git archive -o $temp_file $commit; Expand-Archive -path $temp_file -destinationpath $path
}
</code>
===== Extract specific file(s) from specific commits and put in a specified path =====
==== Example in Powershell ====
<code powershell>
$archive='c:\path\to\archive.zip';
git archive --format=zip <commit> <file(s)> -o $archive;
Expand-Archive $archive -DestinationPath 'c:\path\to\destination'
</code>
====== git-extract ======
Using Powershell, extract the files from a specified commit to a destination folder.
<code powershell>
param(
    [Parameter(Mandatory=$true)] [String]$commit,
    [Parameter(Mandatory=$true)] [String]$DestPath
)

$archive="$env:temp\$([System.IO.Path]::GetRandomFileName()).zip"
git archive --format=zip $commit -o $archive
Expand-Archive -Path $archive -DestinationPath $DestPath -Force
</code>

=== Example Usage ===
<code powershell>
git-extract head $env:temp\foobar
</code>
====== Secondary Commands ======
Get URL for remote repo.
<code bash>
git config --get remote.origin.url
</code>

====== Related ======
  * [[Github]]
  * [[Powershell Git]]
  * [[https://www.conventionalcommits.org/|Conventional Commits]]
  * [[Handy Git Commands]]