creativecoder/Git Notes.md

## Git Notes.md

      
    Raw
  

              Git Notes.md
            
          
    Git Version Control


Understanding git

Anatomy of git

HEAD

Think of it as the snapshot of your last commit
Pointer to the current branch reference, which is the last commit you made or the last commit that was checked out


Index

Snapshot of your next commit
Includes all of the files from your previous commit plus the changes you've staged


Working directory

These are the actual files on your filesystem


Configuration

--version - lists the version of the git install
Update from within git using: git clone http://github.com/git/git.git (run as sudo for to update for all users)
Config file comes in 3 flavors:

--global

stored in ~/.gitconfig; specific to user


--system - stored in /etc/gitconfig and applies to every user and all their repositories
--local - stored in .git/config within each repository directory and applies only to the repository


Check the config file: config --list
Can also use config {key}, like config user.name to check a specific key
Set user name and email for recording commits

config --global user.name "Name"
config --global user.email "email@domain.com"


To use a different text editor (uses the default system editor, usually Vi or Vim: config --global core.editor emacs (will use the emacs editor) or nano
To use a different diff tool: config --global merge.tool vimdiff (will use vimdiff)
Set up aliases

config --global alias.[alias-name] [git-command] will setup git to trigger the specified command using the alias
Ex: git config --global alias.co checkout would trigger a checkout command when get co is typed
Ex: git config --global alias.unstage 'reset HEAD --' makes it easier to upstage a file
Ex: git config --global alias.last 'log -1 HEAD' allows you to just see the last commit
Note that if you want to trigger an external command with an alias, prefix it with !; Ex: git config --global alias.visual "!gitk"


Enable autocompletion

git-completion.bash file located in the contrib/completion directory in source code
To enable for current user

Copy file to home directory
Add "source ~/.git-completion.bash to your .bashrc file


To enable for all users

Copy file to /opt/local/etc/bash_completion.d directory


Alternatively, create the following two files in your home directory

.bash_profile - "source ~/.bashrc"
.bashrc - "source /usr/local/git/contrib/completion/git-completion.bash"


Press the tab key when writing a git command to see suggestions


Fix permission issues

Set get to ignore file permission changes: git config core.filemode false


diff/difftool

git config --global color.ui true to enable colors in diff output
http://git-scm.com/book/en/Customizing-Git-Git-Configuration
http://www.andymcintosh.com/?p=33
Prevent mergetool from keeping .orig backups (doesn't work with all mergetools): git config --global mergetool.keepBackup false


Help for any git command help <verb>, <verb> --help, or git-<verb>


Creating Repositories and Managing Files

init

Use init by itself within an existing directory to convert that directory into a git repository
Create a new repository in a new directory with init directoryName


add * or add [filename]

For untracked files: adds to the repository to be tracked by git
For tracked files: stages file to be included in the next commit
Note that adding a file stages it in the state its in when it's added. If you modify the file further, those changes won't be staged until you add it again
add . or add folder/ adds the current directory and everything under it (but doesn't handle deleted files)
Wildcard searches can be done with \\* (need to escape the * character)
add -u adds all file changes for files that are already tracked, including deleted files
add -A does both add . and add -u, when you want to add new files and remove deleted files


status - tells which branch you are on and status of files (tracked, changed, staged, etc)
diff 

Tells what you've changed but not yet staged
diff --staged (or --cached) - tells what you've staged buy haven't yet committed


a. rm [filename]

Stages the file for removal; at the next commit, the file will no longer be tracked
If you simply remove the file without the git command, it will show up as changed but not updated (aka untagged)
-f is used to remove a modified file already added to the index (this overrides the safety feature that prevents you removing a file that hasn't been recorded in the repository yet)
--cached will remove the file from being tracked, but keep it in the directory (useful if you forgot to add something to .gitignore
file-glob patterns like

git rm log/\\*.log - removes all files with the .log extension in the log/ directory
git rm /*~ - removes all files that end with ~


mv [oldfilename][newfilename]

Used to rename a file, but not really needed, because git will figure out that you renamed files
Equivalent to running these 3 commands

mv oldfilename newfilename
git rm newfilename
git add newfilename


reset [filename] unstages a file
checkout -- [filename] will revert the file to its state at the previous commit (and all changes are GONE FOREVER)
stash - stores changes you don't yet want to commit

Stores stashes in a stack, with the most recent on top

--keep-index will only stash changes that have not been added to the index with git add


stash list will list all stashes made
stash apply applies the most recent stash

stash apply stash${n} applies the specified stash
Stashes are not deleted when applied
Stashes can be applied on a different branch than where the they were made
Stashes can be applied on a branch with uncommitted changes
Use --index with stash apply if your stash contains changes to a file that is already staged and you want the stashed changes to be staged as well


stash drop [stash-name] to delete a stash
stash pop [stash-name] to apply and delete a stash at the same time
Un-apply a stash: git stash show-p [stash-name] | git apply -R (assumes the most recent stash if you don't supply a stash name)
Create  a new branch from a stash: git stash branch [branch-name]

Creates a new branch, checks out the commit you were on when you created the stash, reapplies the stash there, and drops the stash if it applies successfully
Then you can merge the branch back into your main working branch when you're ready


Create a stash-unapply command: git config --global alias.stash-unapply '!git stash show -p | git apply -R'


.gitignore file contains rules for excluding files from the repository

Blank lines or lines starting with # are ignored within the file
Standard glob patterns work

* matches zero or more characters
[abc] matches any character inside the brackets
? matches a single character
[0-9] matches any character within this range
Use a \ to escape special characters (like # and !)


Paths

End patterns with / to specify a directory
* within a path will not match any directory, only the final filename
A leading / matches the beginning of the path name

/*.html matches index.html but not /home/index.html


A leading **/ means match an in any directory
Trailing /* means match anything within a directory
foo/**/bar means match 0 or more directories inside foo that contain bar


Negate patterns by starting it with !


update-index --assume-unchanged

Ignore uncommitted changes in a file that is already tracked


git ls-files lists all of the files currently being tracked in a repo


Remotes

clone - create a working copy of a repository

Automatically adds the remote repository as origin
From local to local: clone /path
From remote

clone git://url/file.git (uses the git protocol; can also use http or https)
clone user@server:/path/file.git will use ssh
Folder name: by default the folder name is the same as the cloned repository; you can also specify a folder name after the path to the file


remote lists the shortnames of each remote handle you've specified

origin is the default name of a server you've cloned
ssh remotes are the only kind you can push to
-v shows the URL associated with each shortname


remote add [remote-name] [url]

Will assign a shortname to the repository at the specified url
Then use the shortname to reference the url with any git command
[shortname]/master will access the master branch
remote add origin <server> - connect existing repository with remote server and set that server as origin


remote show [remote-name]

Lists the URL for the remote repository and tracking branch information and all remote references that have been pulled
Shows which branch is automatically pushed when a push is executed, "new remote branches" (branches on the remote you don't have locally yet), "stale tracking branches" (remote branches you have that have been removed from the remote server), and tracked remote branches (that are automatically merged when pull is executed)


remote rename [filename] [newfilename] renames a remote reference
remote rm removes a remote reference
remote update fetches from all remote repositories
Remote tracking branches

branch -r lists all remote tracking branches

-a lists all branches


fetch [shortname or url]

Gets all of the of the information from a remote repository and puts it in its "remote tracking" branches called [remote-name]/[branch-name]
Does not merge it or modify any of your work--this has to be done manually
--all gets updates from all remotes
Ex: fetch origin fetches any new work that has been pushed to that server since you cloned or last fetched from it


Merge into current branch using merge [remote-name]/[branch-name]
Peek at remote branches (without working on them)

Check them out directly: git checkout origin/dev


Create new local branches from remote tracking branches

checkout --track [new-local-branch-name] [remote-name]/[branch-name] (you can leave out local branch name if you want to use the same branch name as the remote)


pull

Generally fetches data from the server you originally cloned from and tries to merge it into the code you're currently working on
In general, you don't want to do this (use fetch and merge instead)
--all will download all remote branches
Pull and overwrite local, untracked files

git fetch --all to fetch the remote changes
git reset --hard origin/master reset local files to status of remote


push [remote-name] [branch-name] - send changes to remote repository

push origin master pushes your local master branch to the original server you cloned it from
Only works if you have write access to the server, and it hasn't been modified since you cloned/pulled it last
You have to pull the changes to incorporate them before you push, if you don't have the most recent version of the repository
push [remote-name] [branch-name]:[remote-branch-name] will specified a different name for the remote branch
git push [remotename] :[branch] will delete a remote branch from the server
-u will set as the default remote tracking branch (upstream) repository
-f will force updates (like when removing commits that have already been pushed)


PUSH directly to a website

Create a "bare" repository on the server, in a different directory than the web root: git init --bare
Create a file called post-update in the hooks folder of this new repository with the following line: GIT_WORK_TREE=/path/public_html git checkout -f (this should be the entire path to the web root, like public_html)
Give yourself execute permissions on this file: chmod +x /path/website.git/hooks/post-update
On the local machine, add a new remote server: git remote add [shortname] [user@server.com:/path/server/website.git]
Use this as the initial push command: git push website +master:refs/heads/master
Then you can use the normal push command to update the site: push [server-name] [branch-name]


Github

When forking a repository, create a new remote called upstream that links to the original repository so you can update it.


Managing Commits

commit - creates a current snapshot of the repository as it is

Opens a text file with a summary of the commit
-m is for including a message (in quotes) after the command that identifies the commit
-v will push the output of diff to the text file
-a will skip the staging area and automatically stage every file that is already tracked before executing the commit
--amend will add changes to previous commit

If you don't specify a new commit message with -m, you'll be given the previous commit message
Will create a conflict with commits that have already been pushed to a remote host


log

Default command lists the commits made in that repository in reverse chronological order
Note the difference between "author" (the person who wrote the patch) and "committer" (the person who executed the commit command)
-p shows the diff introduced in each commit
--stat shows abbreviated statistics for each commit
--shortstat displays only the changed/insertions/deletions line from --stat
--pretty=[format] changes the format of the log output

oneline prints each commit on 1 line
short, full, and fuller provide increasing levels of information
format: lets you specify your own formatting


--graph shows an ASCII graph with your branch and merge history
--name-only shows the list of files modified fate the commit information
--name-status shows the list of files affected with added/modified/deleted information as well
--abbrev-commit shows only the first few characters of the SHA-1 checksum
--relative date - display the date in a relative format
Limiting log output

-2 limits the output to the last two entries
--since= and --after=  get the commit history within a specified timeline, like --since=2.weeks or --until="2012-08-15"
--until= and --before= do the same but opposite of the above
--author= specifies a specific author
--committer= specifies the person who executed the commit
--grep= lets you search for keywords
use --allmatch if you use both --author and --grep commands for your query; otherwise all items that match each of your queries will be retrieved
Specify a directory of filename by adding it last, following --


gitk is a gui tool to visualize log searches (type gitk to activate it


Undoing changes - be careful, you can't always undo (revert) your undos!

commit --amend will add whatever is in your staging area to your most recent commit (uses the same commit message as the original, unless you change it)


reset [options] [hash/tag] [path/files] reverts to a previous commit

Points the head to the previous commit
Options

--soft keeps the state of the files the same, so you can see the differences (like undoing commits without changing the files)
--mixed also updates the index from the specified commit, as if your files were not yet staged for the next commit (this is used if nothing is specified)
--hard resets all files to the status of the preivous commit


Specify a path to effect only specific files or directories
Squash commits

Reset to the first commit you want to keep: reset --soft HEAD~2 (moves back 2 commits) or specify a hash
Run git commit


reset [hash/tag] file will reset the index (staging area) for that file, but not change the version in the working directory (until you commit, of course!)


revert [hash] - reverts to a previous commit

Will bring up an editor to revise your commit message (quit out of it if you don't want to change this message)


blame [path/filename]

Tells you who is responsible for a certain section of code
-L[start],[end] will only output specific lines


Tagging Files

Info

Often used for marking release points
Two kinds

Lightweight - a simple pointer to a specific commit
Annotated - full objects that have their own checksum, tagger name, tagger email, date, message, and can be signed and verified


Are not pushed by default 


tag lists the current tags in alphabetical order

-l '[search]' lists tags that have a particular format; Ex tag -l 'v1.4.*' will list all of the tags that begin with "1.4"


tag [name]-lw creates a lightweight tag
tag -a [name] creates an annotated tag

-m '[message]' creates a message; otherwise git opens the editor once a tag is created


show [tagname] will show information about a tag
Signed tags

tag -s [name] creates a new annotated tag signed with GPG (assuming you have a private key)
tag -v [tag-name] uses GPG to verify the tag signature (you need the signers public key in your keyring


Create a tag for a previous commit

Add part (or all) of the checksum at the end
Ex: tag -a v1.2 8fceb02


To push tags (just like sharing remote branches)

push [remote-name] [tag-name] would push the specified tag to the named remote server; Ex: git push origin v1.4
Use --tags option on the push command to push all of your tags; Ex: git push origin --tags


Branches

HEAD is what keeps track of which branch you're on; the default branch is "master"
branch

Lists the current branches, with a * to indicate the current branch you're on
-v lists the most recent commit with each branch
--merged shows which branches are already merged into the branch you're on (these you can usually delete because you've already merged the code)
--no-merged shows what branches that contain work you haven't merged


branch [branch-name]

Creates a new branch
-d deletes a branch
-D deletes a branch that hasn't yet been merged
-u [remote-branch] [local-branch] will set the specified local branch to track the specified remote branch (if no local branch is specified, the current branch is used)


checkout [branch-name]

Moves the head to another branch
If your working directory or staging area has uncommitted changes that conflict with the branch you're checking out, you can't switch branches
-b creates a new branch and switches to it
-a will list all branches, including those from remote repositories
Tracking branch

Use -b to create a local working copy of a remote branch you have fetched: git checkout -b [new-local-branch-name] [remote-name]/[branch-name]
--track is shorthand for this; Ex: git checkout --track [remote-name]/[branch-name] will create a new local branch with the same name as the remote branch
Tracking branches can then be pushed and pulled (when checked out) without specifying server information, because git remembers where they originally came from
Delete a remote branch from the server: git push [remotename] :[branch]


merge [branch-name]

Merges a branch into the branch you specify
If the working branch is just an addition commit of the branch merging-to branch (that hasn't been changed since the working branch was created), it just moves the pointer of the merged-to branch

Use merge --no-ff [branch-name] to prevent a fast-forward merge, if you want to maintain the history of the branch
--ff-only will abort the merge if not able to do a clean fast foward merge


If the merged-to branch has been changed, merges by recursive, creating a special "merge" commit that has more than one parent
You can merge the master into your working branch, if you need to (from the working branch): git merge master


Conflicts

Merge is paused if there are conflicts
See unmerged files in the status
To manually resolve a conflict

Remove everything between and including <<<<<<< and >>>>>>> and replace it with new code
add to stage the file (which marks it resolved)
Check that all conflicts are resolved and added with status
commit and specify what you did in the commit message


mergetool starts a visual merge tool to walk through conflicts
clean will recursively remove files that are not under version control

-f to force clean (required if clean.requireForce is not set to false)
-x will also remove ignored files (specified under .gitignore; normally these files are not cleaned)
-d remove untracked directories in addition to files
-n or --dry-run
-X remove only files ignored by git


Remote Branches

References to the state of branches on your remote repositories
Take the form [remote]/[branch]
Never updated automatically--you must push the branches you want to share (this way, you can keep your code private until it's ready to share


Rebasing

Take all changes that were committed on one branch and replay them on another branch

Essentially takes the branch and makes it the next commit in the branch you're rebasing to
You can then do a fast-forward merge, because both commits are in the same stream
Has the advantage that it leaves a clean history; good for contributing to a project that you don't maintain, because it will just add another commit to the main branch


rebase [branch-to-rebase] (from within the target branch to which you are rebasing)
rebase [branch-to-rebase] [target-branch] will take the branch to rebase and rebase it into the target branch without checking out the target branch (you are then switched to the target branch)
--onto rebases a branch over top of another one, if the working branch and rebase-to branch aren't directly connected
DO NOT rebase commits that you have pushed to a public repository--instead use it as a way to clean up work with commits before you push them
Interactive rebase - squashing commits

-i HEAD~n where n is the number of commits to squash
You can then edit the rebase process to combine or skip commits as needed
Use mergetool to fix any merge conflicts while rebasing
--continue will continue the rebase once merge conflicts are fixed
--skip will skip the current commit that has an error
--abort will abort the rebase and return to the most recent commit


cherry-pick [commit] - add a specific commit

Ex: cherry-pick master [commit-hash] would add that commit from master to the current branch


Subtree

subtree split breaks off a subfolder, extracts the relevent commits, and allows it to become it's own repo

Ex: git subtree split --prefix=web --onto deploy -b deploy takes the web folder and puts it in its own branch called deploy

--prefix= selects the folder
--onto selects an existing subtree to apply the split (you don't need this the first time you run this command)
-b declares which branch to use, and creates it if it doesn't exist


Submodules

Usage

Used for putting additional repositories within an existing repository
Submodules should be self-sufficient repositories of code
Good way to include dependencies for your project
IMPORTANT: submodules are tracked separately; if you change files in a submodule, they are not tracked by the parent project! You must commit changes them with each submodule independently
The "superproject" only keeps track of the status of a submodule by its current commit, when a commit is made to the superproject
git push does NOT push a submodules code; push the changes from the submodule first


Best practices for editing submodules

Don't edit submodules themselves; instead edit them as separate projects and pull them into the superproject
If you do edit submodules directly

They will be overwritten with submodule update
Create a new branch within them first, git checkout -b [branch-name] so you can find your work in that branch later, if you need to


Adding submodules

submodule add [source] [path/name]
The submodule will be cloned in the specified directory (sub submodules of this submodule will be empty directories)
submodule init adds .gitmodule info to .git/config file


Managing submodules

submodule status
submodule summary compares submodules current state vs commited state
Merging branches

Whenever you merge in a branch, submodule updates are not included
Submodule updates must be done separately (see below)


Updating submodules

submodule update
Updated submodules are "headless", meaning they don't have a current branch

Switch to submodule directory
git checkout master (or create a new branch)


pull (from submodule directory)
Make a commit in the superproject to save the state of all submodules. If submodules updates are not committed, they are lost


Removing submodules

Remove submodule reference from .gitmodules
Remove submodule reference from .git/config
Remove the created path for the submodule: git rm --cached [path] (no trailer slash)


Cloning with submodules

clone (submodule directories will initially be empty)
submodule init to initialize the submodules
submodule update to pull in the contents from the submodules
Shortcut

clone [source] --recursive to include submodules (and their submodules) in a clone
submodule update --init --recursive if you forgot to do this on the initial clone


Branches and submodules

When switching to a new branch without a submodule, the submodule directory remains, untracked

If you move or remove it, you'll have to clone it back when you switch back to the original branch


Convert subdirectory to submodule

Move the subdirectory out of the superproject into its own project space

Use git filter-branch to extract repository history just for this folder, if needed


Rename the submodule-to-be directory if needed, to be more descriptive
Create a new upstream hosting for the submodule (like GitHub)
Initial new project git init and push to remote, if needed
Add new git module to superproject
Commit and push the super project
If you switch back to a branch that doesn't have the submodule but still has the directory, you need to move the directory out of the way first, so it doesn't get overwritten by the subdirectory from the branch


Debugging

bisect to find the exact commit where a bug appeared

bisect start to get going
bisect bad to mark the current commit that has the bug
bisect good [commit] to name a past commit where you know things worked
The bisect session will start
Test the bug at each stopping point and enter bisect good or bisect bad accordingly
Git will tell you the first commit where the bug appeared
bisect reset to return to where you started


Configuring a git server

Server setup

Install git on the server
Create a git user
Add a ssh key for each person who will be able to access the git user
Change the shell for the git user in /etc/passwd to git-shell (run which git-shell to determine where it's located)
Create a directory in the git user's home directory called git-shell-commands


Gitolite


Install


Create a git user (as above, but maintain regular shell access and don't add keys) and login


~/.ssh/authorized_keys needs to be empty or non-existent


Upload your ssh public key to $HOME/YourName.pub


Run the following commands
  git clone git://github.com/sitaramc/gitolite
  mkdir -p $HOME/bin
  gitolite/install -to $HOME/bin
  source .profile
  gitolite setup -pk YourName.pub


Add users


Do this using the special repository, gitolite-admin


git clone git@host:gitolite-admin on your local machine


Keys - add users' public keyfiles ([user].pub) in the keydir


Repos


Edit the file conf/gitolite.conf
  repo foo
  	RW+                     =   alice
  	-   master              =   bob
  	-   refs/tags/v[0-9]    =   bob
  	RW                      =   bob
  	RW  refs/tags/v[0-9]    =   carol
  	R                       =   dave


Commit the changes and push to your git server


Permissions

R read
W write
+ allows deleting refs
- to deny access


Groups
  @staff      =   alice bob carol
  @interns    =   ashok

  repo secret
  		RW      =   @staff

  repo foss
  		RW+     =   @staff
  		RW      =   @interns


@all


Can be used as an alias for all users or as an alias for all repos
  repo @all
  	R = @all