Difference between revisions of "Workshop: Introduction to version control"

From Design and Build Lab
Jump to navigation Jump to search
m (Kristof moved page Utilizing version control to Introduction to version control without leaving a redirect: Merge and refactor)
m (Kristof moved page Introduction to version control to Workshop: Introduction to version control: retitle for better organization)
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
'''Version control''' is a technique for managing the complexity of adding and modifying information to a project.
+
[[File:Poor_project_management.png|right|frame|Has this ever happened to you? No more, with version control!]]
  
When a project is in its infancy, it is fairly straightforward to keep track of the files contained within; it can, however, become unmanageable very quickly - especially if revisions happen frequently. Version control can be imagined as a series of '''snapshots''' of a project's revisions as time progresses. Each snapshot allows you to see exactly the state of the project at that time; each time you take a snapshot, you are adding another node to its history. You can travel back to any of these snapshots at any time.
+
''(Generally, this workshop is offered at least once a week on a rotating basis. Check the [http://designandbuildlab.com/?page_id=445/ Lab calendar] for up-to-date availability!)''
  
The version control information (the files, the snapshot information, et al.) are held ''locally'' in a folder called a '''repository''', or repo. You can additionally sync this repo to a server somewhere else - called a '''remote'''. This can serve as a backup, as well as a way to ''share'' ''the repo with others'' who may also be working on the project.
+
'''Version control''' is a technique for managing the complexity of a digital project - especially one which is done collaboratively.
  
A '''version control system''' (VCS) is a tool that handles all of this complexity: the repo itself, the snapshots, the remote(s), et al. There are many VCs's; the most popular is called '''[https://git-scm.com/downloads git]'''.
+
== What is version control? ==
 +
When a project is in its infancy, it is fairly straightforward to keep track of the files contained within; it can, however, become unmanageable very quickly - especially if revisions happen frequently. Version control can be imagined as a series of '''snapshots''' of a project's changes as time progresses; it effectively stores the entire history of the project. Each snapshot allows you to see exactly the state of the project at that time; you can travel back to any of these snapshots at any time.
  
=== Terminology ===
+
The version control information (the files, the snapshot information, et al.) are held ''locally'' in a folder called a '''repository''', or repo. Additionally, you can sync this repo to a server somewhere else - this copy of the repo called a '''remote'''. The remote can serve as a backup, as well as a way to ''share the repo with others'' who may also be working on the project.
'''repository''': the location and contents of a project, including all version control information
 
 
 
'''commit''' '''(n)''': a particular snapshot of a project
 
 
 
'''commit''' '''(v)''': to take a snapshot of a project
 
 
 
'''remote''': a copy of project, stored on a server somewhere else
 
  
'''branch''': a particular timeline of snapshots - the main branch is typically called "master"; other branches may be used to develop new features without risking the master branch's stability
+
A '''version control system''' (VCS) is a tool that handles all of this complexity: the repo itself, the snapshots, the remote(s), et al. There are many VCS's; the most popular is called '''[https://git-scm.com/downloads git]'''.
  
 
=== Why use version control? ===
 
=== Why use version control? ===
 
The two advantages that version control provides:
 
The two advantages that version control provides:
 
# ''You are able to travel back in time to any point in a project and utilize it from that moment''; and
 
# ''You are able to travel back in time to any point in a project and utilize it from that moment''; and
# if you use a remote, ''collaboration is not only straightforward, it is encouraged''.
+
# ''Management of a collaborative project is streamlined''.
  
 
== Utilizing version Control ==
 
== Utilizing version Control ==
Why use [[version control]]? The two advantages that version control provides:
 
# ''You are able to travel back in time to any point in a project and utilize it from that moment''; and
 
# if you use a remote, ''collaboration is not only straightforward, it is encouraged''.
 
'''This page's examples assume you are using git.'''
 
 
 
=== Required tools ===
 
=== Required tools ===
 
* A VCS - preferably '''[https://git-scm.com/downloads git]'''.
 
* A VCS - preferably '''[https://git-scm.com/downloads git]'''.
Line 34: Line 23:
 
** [https://bitbucket.org/ Bitbucket] is recommended because it offers free private repos for small teams.
 
** [https://bitbucket.org/ Bitbucket] is recommended because it offers free private repos for small teams.
 
** [https://github.com/ Github] is the most widely used web-based repository.
 
** [https://github.com/ Github] is the most widely used web-based repository.
Git is accessed through the command line interface (CLI) of your choice:
+
* Git is accessed through the command line interface (CLI) of your choice:
*''Windows'': you can use Git Bash (which was installed when you installed git.)
+
**''Windows'': you can use Git Bash (which should install when you installed git) or PowerShell; Bash is preferred because it is nicely color-coded.
*''Linux/OSX'': terminal (which is installed with the operating system)
+
**''Linux/MacOS'': terminal (which is installed with the operating system).
 +
 
 +
=== Acquiring a repo ===
 +
There are two main ways to work with a repo: create one yourself, or use someone else's.
 +
 
 +
==== I want to create one myself! ====
 +
*If you are only going to be working on this repository locally, then:
 +
*# In your CLI, navigate to the place you'd like to save the repo folder: <code>cd [path]</code>
 +
*# Create the repo folder: <code> mkdir [repository folder name]</code>
 +
*# Navigate into the repo folder: <code>cd [repository folder name</code>
 +
*# Initialize the repository: <code>git init</code>
 +
 
 +
*If instead, you are going to be working with a remote, then:
 +
*# Create a new repo on your remote of choice.
 +
*# Locate and copy the url for the git remote. Typically, this is in the top-right corner of the repo's main web page.
 +
*# In your CLI, navigate to the place you'd like to save the repo folder: <code>cd [path]</code>
 +
*# Use the ''clone'' function of git to download a copy of the repo locally: <code>git clone [the_link_you_copied_in_step_2.git]</code>
 +
*# You can now begin working with your repo!
  
=== Setting up a repo ===
+
==== I want to work with someone else's! ====
There are several ways to do this; the easiest way is to create a new repo on Bitbucket or Github, and then duplicate it on your local machine using a CLI of your choice:
+
*This process is also simple: ''find'' a repo that you'd like to work with on a remote, and clone it onto your system:
# Navigate to the place you'd like to save the repo folder: <code>cd [path]</code>
+
*# Find a remote repository you'd like to work with.
# Locate and copy the url for the git remote; in bitbucket, this is in the top-right corner of the repo's main page.
+
*# Locate and copy the url for the git remote. Typically, this is in the top-right corner of the repo's main web page.
# Use the ''clone'' function of git to download a copy of the repo locally: <code>git clone [the_link_you_copied_in_step_2.git]</code>
+
*# In your CLI, navigate to the place you'd like to save the repo folder: <code>cd [path]</code>
You can now begin adding files in your repo!
+
*# Use the ''clone'' function of git to download a copy of the repo locally: <code>git clone [the_link_you_copied_in_step_2.git]</code>
 +
*# You can now begin working with your repo!
  
===Working with a repo===
+
=== Working with a repo ===
  
 
==== Typical workflow ====
 
==== Typical workflow ====
Line 58: Line 65:
 
#'''Commit''' those changes to the repository: <code>git commit -m "[a message describing the changes]"</code>
 
#'''Commit''' those changes to the repository: <code>git commit -m "[a message describing the changes]"</code>
 
#'''Push''' the new commit to the remote repository: <code>git push [remote name] [branch name]</code>
 
#'''Push''' the new commit to the remote repository: <code>git push [remote name] [branch name]</code>
 +
 +
== Terminology ==
 +
'''repository''': the location and contents of a project, including all version control information
 +
 +
'''commit''' '''(n)''': a particular snapshot of a project
 +
 +
'''commit''' '''(v)''': to take a snapshot of a project
 +
 +
'''local''': a copy of project stored on your system
 +
 +
'''remote''': a copy of project stored on a server somewhere else
 +
 +
'''branch''': a particular timeline of snapshots - the main branch is typically called "master"; other branches may be used to develop new features without risking the master branch's stability
  
 
== Common git commands ==
 
== Common git commands ==
Line 65: Line 85:
 
!Function
 
!Function
 
!Example usage
 
!Example usage
|-
 
|status
 
|<code>git status [options]</code>
 
|checks the status of the repo; shows a visual distinguishing among files which have and haven't been included in the repo, files which have been modified and staged, et al.
 
|<code>git status</code>
 
 
|-
 
|-
 
|add
 
|add
 
|<code>git add [filename]</code>
 
|<code>git add [filename]</code>
|stages files; these files are ready to be committed.
+
|stages files; these files will then be committed during a <code>commit</code>.
 
|<code>git add README.md</code>
 
|<code>git add README.md</code>
 +
|-
 +
|branch
 +
|<code>git branch [-b] [new branch name]</code>
 +
|create a new branch; the option -b flag will immediately <code>checkout</code> the new branch.
 +
|<code>git branch experimental</code>
 +
|-
 +
|checkout
 +
|<code>git checkout [branch or snapshot name]</code>
 +
|switches the repository over to a particular snapshot or branch; typically snapshots are referenced by a hash.
 +
|<code>git checkout experimental</code>
 
|-
 
|-
 
|commit
 
|commit
 
|<code>git commit -m "[commit message]"</code>
 
|<code>git commit -m "[commit message]"</code>
|commits changes to the repo, or "taking a snapshot".
+
|writes changes to the repo, otherwise known as "taking a snapshot".
 
|<code>git commit -m "changed header"</code>
 
|<code>git commit -m "changed header"</code>
 +
|-
 +
|fetch
 +
|<code>git fetch [remote branch name]</code>
 +
|grabs the remote branch's snapshots not on the local machine and stored them locally; ''does not merge''. branch name optional.
 +
|<code>git fetch</code>
 
|-
 
|-
 
|log
 
|log
Line 86: Line 116:
 
|<code>git log</code>
 
|<code>git log</code>
 
|-
 
|-
|checkout
+
|merge
|<code>git checkout [branch or snapshot name]</code>
+
|<code>git merge [branch to be merged]</code>
|rolls the repository over in time to a particular snapshot; typically snapshots are referenced by a hash
+
|inserts branch to be merged's snapshots into current branch's history.
|<code>git checkout a65f27</code>
+
|<code>git checkout master</code><br><code>git merge experimental</code><br>merges <code>experimental</code> into <code>master</code>
 
|-
 
|-
 
|pull
 
|pull
 
|<code>git pull [options]</code>
 
|<code>git pull [options]</code>
|checks the remote for any new commits not on your local timeline; if so, downloads them to your local repo, then fast-forwards your local repo to the current snapshot
+
|checks the remote for any new commits not on your local timeline; if so, downloads them to your local repo, then fast-forwards your local repo to the current snapshot. this is effectively a <code>fetch>/code> followed by a <code>merge</code>.
 
|<code>git pull</code>
 
|<code>git pull</code>
 
|-
 
|-
 
|push
 
|push
 
|<code>git push [remote name] [branch name]</code>
 
|<code>git push [remote name] [branch name]</code>
|connects to the remote and copies any new snapshots on your system to it
+
|connects to the remote and copies any new snapshots on your system to it.
 
|<code>git push origin master</code>
 
|<code>git push origin master</code>
 +
|-
 +
|rebase
 +
|<code>git rebase [-i] [snapshot or branch name]</code>
 +
|folds all snapshots from current to target snapshot or branch name; this seems like editing history, but is very useful when working on larger teams, to condense your changes into one snapshot (which will be merged into the target branch) so that it doesn't flood the target branch with hundreds of commits from each collaborator.
 +
|<code>git rebase -i master</code>
 +
|-
 +
|status
 +
|<code>git status [options]</code>
 +
|checks the status of the repo; shows a visual distinguishing among files which have and haven't been included in the repo, files which have been modified and staged, et al.
 +
|<code>git status</code>
 +
|}
 +
 +
== Sample git workflow ==
 +
 +
The typical git workflow will depend on whether you're working on a personal repository or on a team.
 +
 +
{| class="wikitable"
 +
! style="text-align:center;"|Simple personal workflow:||Team workflow:
 +
|-
 +
|[[File:Gitworkflow.png|600px]]||[[File:Git_workflow_team.gif|400px]]
 
|}
 
|}
  
== Flow chart ==
+
== External Links ==
[[File:Gitworkflow.png]]
+
Git's [https://git-scm.com/docs git's own reference manual]
 +
 
 +
Roger Dudler's [https://rogerdudler.github.io/git-guide/ simple git guide]
 +
 
 +
Git [https://sentheon.com/blog/easy-git-guide-and-reference-for-the-busy.html guide and reference]
 +
 
 +
Git [https://sentheon.com/blog/git-cheat-sheet.html cheat sheet]
  
== More information ==
+
A very thorough [https://www.sbf5.com/~cduan/technical/git/ reference guide]
Git's [https://git-scm.com/docs reference manual]
 
  
Git [https://sentheon.com/blog/easy-git-guide-and-reference-for-the-busy.html#.WYs4y1WGOUk guide and reference]
+
Git [https://jameschambers.co/writing/git-team-workflow-cheatsheet/ on a team]
  
Git [https://sentheon.com/blog/git-cheat-sheet.html#.WYszfVWGOUk cheat sheet]
+
Another git [https://stackoverflow.com/questions/2428722/git-branch-strategy-for-small-dev-team on a team] source

Revision as of 20:30, 8 May 2019

Has this ever happened to you? No more, with version control!

(Generally, this workshop is offered at least once a week on a rotating basis. Check the Lab calendar for up-to-date availability!)

Version control is a technique for managing the complexity of a digital project - especially one which is done collaboratively.

What is version control?

When a project is in its infancy, it is fairly straightforward to keep track of the files contained within; it can, however, become unmanageable very quickly - especially if revisions happen frequently. Version control can be imagined as a series of snapshots of a project's changes as time progresses; it effectively stores the entire history of the project. Each snapshot allows you to see exactly the state of the project at that time; you can travel back to any of these snapshots at any time.

The version control information (the files, the snapshot information, et al.) are held locally in a folder called a repository, or repo. Additionally, you can sync this repo to a server somewhere else - this copy of the repo called a remote. The remote can serve as a backup, as well as a way to share the repo with others who may also be working on the project.

A version control system (VCS) is a tool that handles all of this complexity: the repo itself, the snapshots, the remote(s), et al. There are many VCS's; the most popular is called git.

Why use version control?

The two advantages that version control provides:

  1. You are able to travel back in time to any point in a project and utilize it from that moment; and
  2. Management of a collaborative project is streamlined.

Utilizing version Control

Required tools

  • A VCS - preferably git.
  • A web-based system to host your remotes.
    • Bitbucket is recommended because it offers free private repos for small teams.
    • Github is the most widely used web-based repository.
  • Git is accessed through the command line interface (CLI) of your choice:
    • Windows: you can use Git Bash (which should install when you installed git) or PowerShell; Bash is preferred because it is nicely color-coded.
    • Linux/MacOS: terminal (which is installed with the operating system).

Acquiring a repo

There are two main ways to work with a repo: create one yourself, or use someone else's.

I want to create one myself!

  • If you are only going to be working on this repository locally, then:
    1. In your CLI, navigate to the place you'd like to save the repo folder: cd [path]
    2. Create the repo folder: mkdir [repository folder name]
    3. Navigate into the repo folder: cd [repository folder name
    4. Initialize the repository: git init
  • If instead, you are going to be working with a remote, then:
    1. Create a new repo on your remote of choice.
    2. Locate and copy the url for the git remote. Typically, this is in the top-right corner of the repo's main web page.
    3. In your CLI, navigate to the place you'd like to save the repo folder: cd [path]
    4. Use the clone function of git to download a copy of the repo locally: git clone [the_link_you_copied_in_step_2.git]
    5. You can now begin working with your repo!

I want to work with someone else's!

  • This process is also simple: find a repo that you'd like to work with on a remote, and clone it onto your system:
    1. Find a remote repository you'd like to work with.
    2. Locate and copy the url for the git remote. Typically, this is in the top-right corner of the repo's main web page.
    3. In your CLI, navigate to the place you'd like to save the repo folder: cd [path]
    4. Use the clone function of git to download a copy of the repo locally: git clone [the_link_you_copied_in_step_2.git]
    5. You can now begin working with your repo!

Working with a repo

Typical workflow

When working on a project locally, your workflow will typically consist of the following:

  1. Modify files within the repository's folder (e.g. changing lines of code).
  2. Stage those changes: git add [filename]
  3. Commit those changes to the repository: git commit -m "[a message describing the changes]"

If you have a remote set up, then two steps bookend the workflow above:

  1. Pull any changes from the remote repository to your local copy: git pull
  2. Modify files within the repository's folder (e.g. changing lines of code).
  3. Stage those changes: git add [filename]
  4. Commit those changes to the repository: git commit -m "[a message describing the changes]"
  5. Push the new commit to the remote repository: git push [remote name] [branch name]

Terminology

repository: the location and contents of a project, including all version control information

commit (n): a particular snapshot of a project

commit (v): to take a snapshot of a project

local: a copy of project stored on your system

remote: a copy of project stored on a server somewhere else

branch: a particular timeline of snapshots - the main branch is typically called "master"; other branches may be used to develop new features without risking the master branch's stability

Common git commands

Command Syntax Function Example usage
add git add [filename] stages files; these files will then be committed during a commit. git add README.md
branch git branch [-b] [new branch name] create a new branch; the option -b flag will immediately checkout the new branch. git branch experimental
checkout git checkout [branch or snapshot name] switches the repository over to a particular snapshot or branch; typically snapshots are referenced by a hash. git checkout experimental
commit git commit -m "[commit message]" writes changes to the repo, otherwise known as "taking a snapshot". git commit -m "changed header"
fetch git fetch [remote branch name] grabs the remote branch's snapshots not on the local machine and stored them locally; does not merge. branch name optional. git fetch
log git log [options] shows a list of all the previous commits in the current branch. git log
merge git merge [branch to be merged] inserts branch to be merged's snapshots into current branch's history. git checkout master
git merge experimental
merges experimental into master
pull git pull [options] checks the remote for any new commits not on your local timeline; if so, downloads them to your local repo, then fast-forwards your local repo to the current snapshot. this is effectively a fetch>/code> followed by a merge. git pull
push git push [remote name] [branch name] connects to the remote and copies any new snapshots on your system to it. git push origin master
rebase git rebase [-i] [snapshot or branch name] folds all snapshots from current to target snapshot or branch name; this seems like editing history, but is very useful when working on larger teams, to condense your changes into one snapshot (which will be merged into the target branch) so that it doesn't flood the target branch with hundreds of commits from each collaborator. git rebase -i master
status git status [options] checks the status of the repo; shows a visual distinguishing among files which have and haven't been included in the repo, files which have been modified and staged, et al. git status

Sample git workflow

The typical git workflow will depend on whether you're working on a personal repository or on a team.

Simple personal workflow: Team workflow:
Gitworkflow.png Git workflow team.gif

External Links

Git's git's own reference manual

Roger Dudler's simple git guide

Git guide and reference

Git cheat sheet

A very thorough reference guide

Git on a team

Another git on a team source