class: center, middle # More Fun with Git ??? Notes for the _first_ slide! --- # ♥ Git ♥ ## Git can be challenging <br> * What do you find confusing? * What did you struggle with when creating a repository? * What do you think would be helpful to overcome these challenges? --- # Git Conceptual Road Map <div style="text-align:center"><img src="http://blog.podrezo.com/wp-content/uploads/2014/09/git-operations.png" alt="gource" width="700" /></div> (image source [http://blog.podrezo.com/git-introduction-for-cvssvntfs-users](http://blog.podrezo.com/git-introduction-for-cvssvntfs-users/)) --- # Git Best Practices * Commit often. Keep commits small and frequent. This also helps you have informative commit messages -- * Make sure every commit "works". Never commit if it doesn't compile, runs with errors, or requires files that only exist in your workspace. Since commits are snapshots, this should mean a working snapshot. -- * Write commit messages that will be readable and useful to others and *future-you*. (This is really difficult.) Also, remember when your repository is public, anyone can see your commit messages. -- ---------------------------------------------------------------- <blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr"><a href="https://twitter.com/mtholder?ref_src=twsrc%5Etfw">@mtholder</a> motivating git: You mostly collaborate with yourself, and me-from-two-months-ago never responds to email. <a href="https://twitter.com/swcarpentry?ref_src=twsrc%5Etfw">@swcarpentry</a></p>— Karen Cranston (@kcranstn) <a href="https://twitter.com/kcranstn/status/370914072511791104?ref_src=twsrc%5Etfw">August 23, 2013</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script> ---------------------------------------------------------------- -- * Use multiple branches. This is one of Git's most powerful features and enhances collaboration and reproducibility. You should also decide on a [workflow](https://www.atlassian.com/git/tutorials/comparing-workflows) (like [this](https://guides.github.com/introduction/flow/) or [this](http://nvie.com/posts/a-successful-git-branching-model/)). --- # Git Best Practices * **Pull from the remote before you do anything in your repository.** This reduces potential merge conflicts. So before you make changes to any files `git pull`, after you make a commit and before you push `git pull`. -- * Don't commit unnecessary files. Often these are files that may be generated by your project and can lead to merge conflicts. You can keep these files in your working directory without being tracked using the `.gitignore` file (or the `~/.gitignore_global` file in your home directory). -- * Review your changes before committing. -- * Use aliases. You can add specific aliases for Git commands in the `.gitconfig` file that lives in your home directory. ``` [alias] hist = log --graph --pretty=format:'%h %ad | %s%d [%an]' --date=short last = log -1 HEAD ci = commit st = status ``` --- # Markdown [Markdown](https://daringfireball.net/projects/markdown/) is a text-based mark-up language that is easily rendered into HTML -- * It has become a staple of reproducible science: -- * it can be rendered on GitHub (also Bitbucket & GitLab) and makes online repositories more readable and accessible -- * it is used as a notebook interface for R ([Rmarkdown](http://rmarkdown.rstudio.com/)) -- * it is used as the markup language for [Jupyter](http://jupyter.org/) notebooks, which provide a notebook interface for many languages, including Python and R -- * There are some freely available editors that make writing in Markdown pretty easy (see the list on the course [Software page](https://eeob-biodata.github.io/EEOB-BCB-546X/)) -- * I made all my slides using Markdown and a HTML template called [Remark](https://remarkjs.com) --- # Markdown ## Let's see some Markdown * It is recommended that all README files on web-based Git hosts be written using Markdown -- * The file extension for a Markdown file is `.md` -- * I will demonstrate in [MacDown](https://macdown.uranusjr.com/) (and [Atom](https://atom.io/)) with the `README.md` from the [Git-Markdown Exercise repository](https://github.com/EEOB-BioData/Git-Markdown-Exercise) --- # Get Help ## No matter the problem (with Git or anything else in this class), someone else has encountered it already. Google is an immensely powerful tool for troubleshooting computational problems -- If you can articulate your problem in the form of a Google search query, you will likely find the answer online -- These will primarily be on [Stack Overflow](http://stackoverflow.com/), like my [search](http://stackoverflow.com/questions/7155870/why-unicode-character-for-hearts-symbol-fails-with-html) for how to include Unicode emoji characters in my Markdown presentation 😎 💻 -- If your problem is unique, you can always submit a question on Stack Overflow --- # Working with Others Once you start working with other people on the same repository, you will encounter some scenarios that we haven't yet covered. -- *What happens when two people commit changes to the repository at the same time?* ??? -- *What happens when two people commit changes to the same part of the same file at the same time?!?* -- *What if I really disagree with the changes someone made to the repository?* -- <br> Let's demonstrate what happens when we merge... ??? to revert (hard) use `git reset` can checkout previous commits temporarily. --- # Git GUIs ## Graphical user interfaces for Git There are several [GUI tools](https://git-scm.com/download/gui/linux) for working with Git These tools may be very helpful for doing things that you don't do every day (when it's difficult to remember the command) They also provide nice ways to visualize your repository tree and `diff` commits, etc. I like [SourceTree](https://www.sourcetreeapp.com/). --- # GitHub Pages ### GitHub provides hosting for websites ([https://pages.github.com](https://pages.github.com/)) * You can create a *free* website hosted on GitHub simply by creating a repository in your account called `username.github.io` * For example, here is a nice website by Elizabeth Karan, a PhD student at UCLA (this site uses Hugo, a framework for static site generation): [https://eakaran.github.io](https://eakaran.github.io) -- * My lab website ([http://phyloworks.org](http://phyloworks.org)) is hosted on [GitHub](https://github.com/phyloworks/phyloworks.github.io), using a [Bootstrap](http://getbootstrap.com/) CSS template. If you [purchase](https://www.namecheap.com/) your own domain, it is simple to [redirect](https://help.github.com/articles/using-a-custom-domain-with-github-pages/) your GitHub Pages site to the new domain. -- * You can create a website for any GitHub project repository, simply by enabling GitHub Pages in your settings -- * The [website for our course](https://eeob-biodata.github.io/EEOB-BCB-546X/) is rendered in HTML by GitHub Pages, too. We do this by simply enabling GitHub Pages in the _settings_ of our repository. Then we modified a free [Jekyll](https://jekyllrb.com/) theme called [Millidocs](https://github.com/alexander-heimbuch/millidocs). There are many nice [Jekyll pages](http://jekyllthemes.org/) out there. --- # Git Collaboration ### Now that we all have repositories on GitHub, let's collaborate! * Get into groups of 2-3 and create a new repository on one of your accounts * Give your collaborators access (push rights) to your repository by inviting them on the GitHub page for your repository * Clone your collaborator's repository * Add and edit files in your collaborator's repository * Commit and push those changes to the remote * Pull the up-to-date changes and now try to create a merge conflict! (Edit the same line.)