Git EssentialsPresentation prepared and delivered by Eliot W. Kimber, Contrext LLC

OASIS DITA TC education session16 August 2018

Git Repository Basics

• Commits, not files• Local repos• Remote repos• Two-phase commit mechanism• Pushing and Pulling

Don't Panic

• Very hard to lose work when using git• Can always just make a copy of your local repository if you are afraid

you might mess something up• A little discipline goes a long way• Use tools like SourceTree to do more complicated operations• No substitute for communication with your team

Git repositories

• A git "repository" is a collection of files and the changes to those files over time

• All the history is maintained locally as part of the repository metadata• There's very little "magic" in a git repository

• A git repository is first and foremost just a directory structure with files• You can copy, move, share, etc. a git repository directory

• As long as you don't delete the ".git" directory in the repository it's hard to lose data

Git manages commits, not files

• A git repository is a set of "commits"• A "commit" is a set of changes made to one or more files, committed

as a single atomic action• Each commit has a unique identifier that reflects the changes in the

commit• The same commit (set of changes) can exist in multiple repositories

and will have exactly the same ID• A time sequence of commits represents the history of a set of files• Git compares files by content, not name or directory

Branches are just sets of commits

• Git repositories are organized into one or more "branches"• A branch is just a sequence of pointers to commits• The newest commit on the branch is the "HEAD" commit• When you create a new branch you are just creating a pointer to a

specific commit and giving it a name• Because they are just pointers to commits, branches are light weight

• Compare with Subversion, where branches are separate directory structures• Creating a new branch does not require copying any files• By convention usually have a branch named "master" and then other

branches

Local and remote repositories

• Git repositories are distributed• Any directory can become a git repository• No requirement that any git repository be associated with any other git

repository• A directory on your machine that is a git repository is a "local repository"• Any other repository that you can connect to can be used as a "remote

repository"• There is no built-in notion in git of a single master shared repository

• But that's usually how we use it, e.g., using BitBucket or GitHub or whatever as the master shared repository

• But any two repositories can be remotes of each other

Local and Remote Repositories (one remote)

Local gitrepo

C:\workspace\project-x

My development machine Github server

Push toPull from

Remote "origin"

Github-managed

repo

git:/github.com/oasis-open/project-x.git

Cloned from

Remote repositories

• You can link one git repository to any number of "remote" repositories• A remote repository is simply another repository that you have linked your

local repository to as a "remote":

git remote add name URI-of-remote-repository• You push and pull branches to and from remote repositories• By convention, the first or only remote repository is named "origin"

• E.g., when you clone an existing repository• You can add or remote remote repositories at any time • By convention, the second remote, if there is one, is called "upstream"

• E.g., a repository you "forked" to create your repository

Local and Remote Repositories: Origin and Upstream

Local gitrepo

C:\workspace\project-x

My development machine Github server

Github-managed

repo

git:/github.com/drmacro/project-x.git

Push toPull from

Remote "origin"

Github-managed

repo

git:/github.com/oasis-open/project-x.git

Remote "upstream"

Pull from

Forked from

Cloned from

Git uses two-phase commit

• Files are committed in two phases:• Phase 1: Stage files for commit (git add)• Phase 2: Commit files to the local repository (git commit)• This lets you precisely control which files are committed and when• Best practice:

• Commit related sets of changes together• Makes it easier to track change history• Makes it easier to undo things

• Better to commit small sets of changes more often

Pushing and Pulling

• When you "push" you are sending the commits on a branch to a remote repository

• When you "pull" you are getting commits on a branch from a remote repository

• Pushing and pulling syncs up the history of the two repositories for those branches

Branches

• Branches in git are "light weight"• Easy and quick to create and delete

• Use branches to isolate your work and avoid merge problems• Basic workflow:

1. Pull shared branch to ensure you're up to date (e.g., pull develop branch)2. Create new branch specific to the current task (a "feature branch")3. Make your changes, committing as often as appropriate to new branch4. When task is complete, merge feature branch into main branch5. Push main branch to remote repo

• Wrinkle: somebody pushes stuff to the main branch before you're ready to merge in your changes—calls for "rebase"

Essential git commands• Get status of repository:

git status

• Checkout or create and checkout a branch:

git checkout branchname Checks out existing branchgit checkout –b branchname Creates new branch

• Stage files for commit (git add):

git add –a .git add path-to-file

• Commit staged files:

git commit –m "commit message"

• Delete a branch:

git branch –d branchname

• Rebase current branch on target branch:

git rebase -i target-branchname

Git Usage Principles

• Try to keep your repo up to date with shared repository• Use feature branches to manage work on short-term tasks

• Create feature branch• Do work• Merge feature branch to main branch• Delete feature branch

• Use meaningful commit messages• Use SourceTree or similar to review changes before committing• Commit sets of related changes together

Feature Branches

• Branch created in order to work on a specific feature• Usually local to your repository but can be shared if necessary• Once work on feature is complete, merge feature branch back to main

branch and delete the feature branch

Using Stash• The "stash" feature lets you temporarily save current state of your work and get it back• Stash current state:

git stash

• Recover stashed changes:

git stash pop

• Typical workflow:1. You've made changes you're not ready to commit2. Somebody pushes changes you want to get3. Do "git stash"4. Pull updates5. Do "git stash pop"6. Now you're synced with latest updates and back where you were

Handling Merge Conflicts

• Avoiding merge conflicts• Communicate with team members• Use branches to isolate work on a task• Commit and update often

• Resolving merge conflicts• Can choose use "mine" or "theirs" if you know which version you really want• Otherwise, let git create a "merge report" and manually resolve the conflicts

in the files• Once conflicts are fixed, must "mark as resolved" and then commit the

changes

Cherry Picking

• Sometimes you just want a specific commit added to your current branch

• Can "cherry pick" a specific commit• Adds just the changes in that commit to the current branch• Use SourceTree to do this—command line is too hard

Rebasing Branches

• You have a branch, branched from "develop", you've made changes on• Somebody else pushes commits to "develop" that you know don't conflict

with anything you've done on your branch• You want to "reset my branch to reflect latest commits on develop branch"• You do this with rebase• Rebase basically replays the changes on your branch onto the updated

branch, bringing your branch back into sync with main branch• IMPORTANT: You should only do this for branches you haven't pushed to a

shared repository

Pull Requests

• When you have a fork• Push changes to your fork on a feature branch• GitHub (and other shared git servers) can create a "pull request"

against the "upstream" repository• Pull request is a request for owners of upstream repo to pull your

changes into their repo• Makes it easy to manage contributions from people who do not have

commit rights• Can commit updates to a pull request until it is pulled