Collaboration Tools for Project 1

Git is the industry-standard tool for collaborating on a codebase. Using it to collaborate is more difficult than using it as a sole developer (you’ll need to learn how to avoid and resolve merge conflicts when two people edit the same code at the same time). However, if you take time to learn how to use git properly, that experience will benefit you for years to come!

Working together synchronously

Git is mostly oriented for teams where people are working on different parts of a codebase. Using it to collaborate on the same parts of the code at the same time can be difficult, because doing so creates merge conflicts (you edit Debugger, your partner edits Debugger, and then you try to sync your changes and git doesn’t know what to do with the two sets of changes).

From my experience, the best way to collaborate synchronously is to use an editor plugin that implements Google Docs-style sharing. Here are some that I found from a quick Google search:

• VSCode: Live Share works extremely well. If you’re using VSCode, please give this a try! This is what I’ve used with success in the past.
• Floobits has plugins for IntelliJ, Sublime, Atom, and others. You can get free private workspaces by using an education account.
• CodeTogether is one I haven’t heard of before, but they’re offering all features for free during the COVID-19 pandemic. May be worth checking out if you don’t like the other options.
• TeamHub looks similar (I also have never tried it)

Tips for collaborating with git

Here’s a quick summary of what you’ve probably encountered with git so far in 110L:

• Making a commit. This is when you save a “snapshot” of your code at a moment in time.
  • You do this by running git add . and then git commit -m "<commit message>".
  • “Adding” puts some changes in a “staging area”. (You can add individual files by listing them, but I usually recommend navigating to the root director of your repo, then running git add . to add everything.)
  • git commit takes everything from the staging area and puts them into your “snapshot”.
  • You can both add and commit at the same time using git commit -am "<commit message>".
• Pushing to GitHub. GitHub is an online hosting provider build around git. Running git push will push any local commits (changes you have “committed” with the instructions above but not yet “pushed”) to your repository on GitHub.
• Checking the status of your repo. The git status command allows you to inspect the “state” of your repo: what changes you’ve made, staged, committed, and pushed. It can be helpful to run git status after committing and pushing changes, to make sure that all changes you made ended up in the GitHub repository.
• Cloning a repo. This is how you get the starter code, and set up your local git branches to “track” with the remote branches on GitHub. Once you’ve “cloned” a repo, git push and git pull will work.

Here are some specifics about working together:

• Running git pull will “pull” the most recent version of the repository to your local machine. For example, if your project partner committed and “pushed” a change to the repository, you can get that change by running git pull.
• A merge conflict happens when two people change the same part of a file (e.g. the same function). Coordinate changes with your partner so that you aren’t touching the same code at the same time.
  • That said, if a merge conflict happens, it’s not the end of the world. Merge conflicts are common, and there are great tools built for resolving them.
• Make frequent, small commits. A gigantic commit is very likely to create merge conflicts! Also, if you break something, it’s easier to go back and fix it if you’ve been making incremental commits along the way. You can always merge small commits into bigger ones, but you can’t easily split large commits into smaller ones.
• Write good commit messages. Not only will this help your partner understand the changes you made, but it will also help in resolving merge conflicts, since you can more quickly understand what changes are conflicting. Here’s an article about commit message style.
• Push and pull often. It’s always a nightmare when two people independently make a large number of changes, then attempt to push and are forced to resolve a stack of 15 commits. Run git push (to push your local commits) and git pull (to pull the most recent remote version of the repo) often.
• Say you have made some commits, and your partner just pushed their commits to the server. You won’t be able to push your commits until you pull their commits and reconcile them with your changes. If you run git pull, git will download their commits and attempt to merge them with yours. If successful, it will commit a new “merge commit” that merges the two sets of changes. However, if you do this often, your git history will end up cluttered with merge commits. I prefer to run git pull --rebase, which downloads your partner’s changes, then re-commits your changes on top of them. It avoids creating merge commits in the history.
• Branches are a useful feature of git that allow contributors to establish separate “threads of development” in a codebase. Since this project is small and since the milestones should be completed in order, I don’t think you’ll need branches here. If you’re curious (you will inevitably encounter branches in the future), this article gives a good summary, this website has a great interactive visualization of how branches work, and this tutorial has an explanation of opening a pull request to merge changes from a branch into the “main” branch of your repo.