============================================= An introduction to Git ============================================= .. class:: center January 7, 2015 Department of Aerospace Engineering, IIT Bombay :Author: Prabhu Ramachandran Agenda ========= - Introduction to git - Using github and collaborating - Workflows Motivation ================== .. image:: img/phd101212s.gif :scale: 50% :align: center Credit: www.phdcomics.com History ========= - VCS: Version Control Systems - RCS - CVS - SVN - Centralized repositories Distributed VCS ================== - Peer-to-Peer system - Darcs - Bitkeeper - Mercurial: hg - Monotone - Bazaar: bzr - Git Collaboration =============== - Sourceforge.net etc. - github/bitbucket etc. Introduction to git ====================== - Version control - save work - review changes - do not lose history - share with others - reduce mental burden - Distributed workflow - Requirement for modern software development! Basic model ============= - A series of changesets (commits) - HEAD is the last commit Getting started ================= Setup your details:: $ git config --global user.name "Guru Programmer" $ git config --global user.email "your_email@youremail.com" Create a repository ==================== Create a repo:: $ cd my_project $ git init Note that a ``.git`` directory is present! Help! ======== Find help:: $ git help $ git help merge Status ======== Helpful status of repository:: $ git status Often provides hints Basic commands ================= Add a file:: $ vim readme.txt $ git add readme.txt $ git status $ git commit Changing the default editor ============================= ``commit`` will use ``$EDITOR``. Change this with:: $ export EDITOR="emacs -q" $ export EDITOR=nano Or :: $ git config --global core.editor "emacs -q" A note on commit logs ======================= :: First line brief <= 50 chars Detailed information below. Ideally wrapped to 72 cols. - ALWAYS leave a good log message. - Bullet points are fine. - Multiple paras separated by blank line. Review history ================ What happened:: $ git log - Note the commit "ID" - These are unique IDs Notes ====== - What happens when you commit? - What happens when you add? - The staging area - New files always must be added - Remember to ``git add``! Making changes =================== Make changes:: $ vim readme.txt $ git status $ git diff $ git add readme.txt $ git commit Some useful options ==================== - Add all changed files and commit:: $ git commit -a Commit log on command line:: $ git commit -m "Fix for bug #123" See changes in log:: $ git log -p Exercise ========= 1. Create a dummy repo. 2. Add some files. 3. Make different changes and commit them. 4. Review the log. History ======== - ``HEAD`` is the latest - ``HEAD~1``, ``HEAD~2`` is one/two changes before - You can use the commit IDs (or a unique substring) :: $ git diff HEAD~1 readme.txt $ git diff 737e86dd9 readme.txt Differences between two points:: $ git diff HEAD~2..HEAD~4 readme.txt Recovering old versions ========================= Get the previous version:: $ git checkout HEAD~1 readme.txt Same rules as before apply Ignoring files ================ - Add a ``.gitignore`` :: *.dat *.out *.pyc Ignores all files with these extensions Being Lazy: Aliases ===================== Convenient shorthand:: $ git config --global alias.st status $ git config --global alias.ci 'commit -v' $ git config --global alias.co checkout See ``~/.gitconfig`` for details:: $ git st $ git ci $ git co Recap ======== - ``git config`` - ``git init`` - ``git status`` - ``git add`` - ``git commit`` - ``git diff`` - ``git log`` - ``git checkout`` - ``.gitignore``: ignore files Deleting content ================= Removing a file:: $ git rm readme.txt $ git commit -m "Cleaning up" - Does the file go away? - Can you get back the file? Exercise ========= 1. Add a file with a few additional changes. 2. Remove it. 3. Make other changes to other files. 4. Revive the deleted file. Undoing ========= Deleted too quick:: $ git rm readme.txt # Oops made a mistake. $ git checkout -- readme.txt Phew! Saved! Moving content =============== Moving stuff:: $ git mv readme.txt README.txt $ git commit -m "Renaming readme." Some internals ================== - A series of changesets (commits) - Blobs: a bunch of bytes - Tree - Collection of blobs - Other trees - Commits: - Information on who committed it - Points to a tree - Parent to this commit. - Tag: - A reference to a specific commit Branches ========== - Why branches? - Cheap, super-convenient - Allow experimentation Simple repository =================== This is what we had so far .. image:: img/git_branch_basic.png :align: center Branches ========== .. image:: img/git_branch.png :align: center - Can commit on either branch Branch basics ============== - ``master`` is the default branch - Create:: $ git checkout -b new_branch - List branches:: $ git branch - Note ``branch`` branches from current branch More branch commands ====================== - Switch:: $ git checkout master $ git checkout new_branch - Delete:: $ git branch -d new_branch Merging branches ================= - Merge changes from ``new_branch`` to ``master``:: [new_branch] $ git checkout master [master] $ git merge new_branch - Always merges to current branch - Adds the changes from that branch to current one What just happened? ===================== .. image:: img/git_branch_merge.png :align: center Let us take a look at ``gitk`` quickly Exercise ========= 1. Create a new branch. 2. Add some commits there (add files, edit files ...) 3. Check the logs on new branch and master 4. Merge the branch to master. 5. Delete the new branch. 6. Check logs again. HW: Try to delete an unmerged branch. What if there are conflicts? ============================== - Merges can lead to conflicts:: [master] $ git merge foo Auto-merging readme.txt CONFLICT (content): Merge conflict in readme.txt - Edit ``readme.txt`` and resolve conflicts Resolving conflicts ===================== - Look for lines like so:: <<<<<<< HEAD Line in master ======= Same line in my_branch >>>>>>> my_branch - Edit and remove the markers and:: $ git add readme.txt $ git ci Recap ====== - new branch: ``git checkout -b new_branch`` - switch: ``git checkout master`` - list: ``git branch`` - merge: ``git merge new_branch`` - delete: ``git branch -d new_branch`` Recap ====== - Conflicts: - Manually fix files - Remove markers - Add and commit Collaborating =============== - github.com - bitbucket.org - etc. - Provide hosting for a git repository - Plus other powerful features Collaboration Overview ======================== .. image:: img/git_server.png :align: center Basic ideas ============= - ``clone`` the entire repository - ``pull`` changes from server - ``push`` changes to server - Share content with other users Local demo =========== - The principles can be demonstrated without a server! - Consider two users: 1. Alice 2. Bob - Make a server-like repository:: $ mkdir -p server/project $ git init --bare $ cd ../../ Quick demo: Bob =================== Bob:: $ mkdir bob $ git clone ../../server/project Goes to sleep Quick demo: Alice ======================= Alice:: $ mkdir alice $ git clone ../../server/project $ touch readme.txt $ git add readme.txt $ git ci -a -m "Initial commit" $ git push origin master Bob next morning ================== Bob (yawn):: $ git pull $ git pull origin master $ add/commit whatever. $ git push origin master Working together ================= - Lets say both Bob and Alice make changes but Alice pushes first - Git will refuse to allow Bob to ``push`` his changes - So Bob will first pull:: [bob] $ git pull origin master - Resolves any conflicts - Then Bob can push his changes Recap ========== .. image:: img/git_server.png :align: center Working with remote repos ============================== Clone a repo:: $ git clone https://github.com/FOSSEE/SDES2015.git Pulling changes (merges into current branch):: $ git pull $ git pull origin master Fetch only gets changes, it doesn't merge it:: $ git fetch Remotes ======== - The name ``origin`` is called a "remote" - A shorthand to refer to a repo - One can add additional "remotes" - remote is a name for another fork/repo - You could pull/push to these remotes - See ``.git/config`` Sharing ============ - Share your changes by pushing:: $ git push origin master - To push a branch you have made:: $ git push origin my_branch Permissions ============ - You cannot write to every repository! - So how do you contribute? - "FORK" the repository - This makes a clone of repo on github - You have write access to your fork Forking ========== .. image:: img/git_fork.png :align: center Pull-requests ========================= .. image:: img/git_pull_request.png :align: center Contributing to another project ================================= - You cannot write to every repository! - **Fork** their repository: - Makes a copy of their repo on github - This is your repo so you can share it - Push to your fork - Pull master of upstream - Send a pull-request to upstream Pull-requests (PR) ======================= - Fantastic for sharing code - Easy to review/get feedback/change - Process: - Make a branch locally - Push to your fork (typically) - Select branch on bitbucket - "Create pull request" - target PR to pysph/master Managing remotes ================== Add new remotes:: $ git remote add for example:: $ git remote add fossee git@github.com:FOSSEE/SDES2015.git $ git pull fossee some_branch See remotes already defined:: $ git remote -v Managing remotes ================== Renaming:: $ git remote rename origin upstream Delete a remote branch:: $ git br -d branch_to_delete # deletes it locally # This deletes the branch on the server. $ git push origin :branch_to_delete Example: simple workflow =========================== - Single developer with repo on github:: $ git add readme.txt $ git commit $ git push origin master ... Example: two developers =========================== - Two developers collaborating on github - Same as Alice and Bob:: [alice] $ git pull origin master [alice] $ git add readme.txt [alice] $ git commit [alice] $ git push origin master ... [bob] $ git pull origin master [bob] $ vim readme.txt [bob] $ git commit -a -m "Update readme" [bob] $ git push origin master Example: contribute to project =============================== 1. Fork their repo on github 2. Clone *your* fork (origin) 3. ``git remote add https://.../SDES.git upstream`` 4. Make branch locally 5. Add changes to branch 6. Push branch to origin 7. Send PR to upstream Odds and ends: ``stash`` ========================= Stashing lets you stow your changes away without commiting:: $ git stash list $ git stash $ git stash pop More git resources ======================= - Software carpentry lessons: - http://software-carpentry.org/v5/novice/git/index.html - Bitbucket tutorials: - https://www.atlassian.com/git/ - https://www.atlassian.com/git/tutorial - Newbie/Github: - http://readwrite.com/2013/09/30/understanding-github-a-journey-for-beginners-part-1 - http://readwrite.com/2013/10/02/github-for-beginners-part-2 - https://help.github.com/ - Quick: - http://rogerdudler.github.io/git-guide/