<style> summary { font-weight: bolder; } summary:hover { text-decoration: underline; } </style> # **CS200 GitHub Guide**  We use GitHub and git to give you access to project code, to allow you to save your work online so you can access it from anywhere, and to facilitate collaboration on partnered work. In CS200, we will be expecting you to access git through the terminal/command line and through GitHub. GitHub does have a companion app, but we do not recommend you use it and will not be able to support you in making it function. # **What is GitHub?** GitHub is a code-hosting platform that is used by many programmers to save their code and access it from any machine. Think of it like “the cloud” but for code projects! This guide is your go-to resource for help with GitHub/git setup as well as git commands you should know in order to interact with GitHub from your local machine. # **Making an Account** First, you’re going to need a GitHub account which will be an invaluable resource to you for the rest of your computer science career (both at Brown and beyond). To create an account: 1. Go to [www.github.com](http://www.github.com/) 2. Select “Sign up” in the upper right corner 3. Follow the steps on the website to get your account all set up :) # **Installing Git** Thankfully, installing git on your computer is super easy! First, we need check if you already have git installed on your computer. To do this, we'll need to use a terminal, which is how you'll primarily interact with git. If you haven't used a terminal much before, that's okay! You'll gradually learn more in this course and others, starting now! To open a terminal and check if git is installed: 1. First, open the terminal on your computer: 1. **On Mac**: Go to **Applications** > **_Utilities_** > open **Terminal** - (Alternatively, you can open _Spotlight Search_ (keyboard shortcut is “Command+Space’’), search for “terminal”, and open the first application listed) 2. **On Windows**:  Open the Search bar,  enter “command prompt”, and click the first application listed 2. Enter the command `git --version` and press Enter If you already have git installed, your terminal should print the version you have (the version you have shouldn’t matter, as long as you have it installed). You can ignore the rest of this section and skip to [Configuring git](#Configuring-git-settings). If get some error like "command not found", you need to install `git`. To do this, expand the instructions below: <details><summary><b>Instructions for MacOS (click to expand)</b></summary> 1. **In your terminal, enter the command `xcode-select --install`** <br />This will download a set of recommended development tools from Apple, including git. If you want to install git another way, look [here](https://git-scm.com/download/mac). 2. **Follow the prompts to finish the installation.** The process may take several minutes. 3. **Verify you have Git installed** by running `git --version` in your terminal again. You may need to quit and reopen your terminal for this to work. </details> <details><summary><b>Instructions for Windows (click to expand)</b></summary> 1. **Go to [this page](https://git-scm.com/download/win)**. This should prompt an automatic download of git, but if not, click the link to manually download git. 2. **Open the .exe file** you downloaded and click next through each of the installation pages--**there is no need to adjust any settings, all the defaults are fine**. 3. **Verify you have Git installed** by running `git --version` in your command prompt again. You might need to quit and reopen your the command prompt window for this to work. </details> # Configuring git settings Next, we need to to connect git on your computer to your GitHub account. To do this: 1. In your terminal, **enter the command following command**, replacing `<your email here>` with the email you used to make your github account (**don't forget the quotes!**): ``` git config --global user.email "<your email here>" ``` :::success 🚀 **Pro tip (for this guide and the future)**: In software documentation, it's a common convention to type text in `<angle brackets>` as a placeholder for you to fill something in. When you fill in the placeholder **don't include the angle brackets**--they are just notation to tell you it's a placeholder when reading. <br /> Keep this in mind as you read other documentation--learning how to read documentation is an important skill, and one we want you to learn in this course! ::: After you enter the command, you shouldn't see anything print in your terminal--this is expected. Git is configuring itself behind the scenes! (Often, terminal programs don't print anything when they run successfully--many only print a message when something goes wrong.) 2. Next, run another command to set your name (**don't forget the quotes!**). You can set this to your username, or your preferred name: ``` git config --global user.email "<name>" ``` Once again, you shouldn't see any output after running the command. If you don't get any errors, it worked! # Creating your Github access token When you use `git` to connect to Github, you need to provide credentials to Github to prove you are the user you claim to be. To do this, you can create a Personal Access Token--this is similar to a password, but more commonly used when a program (eg. `git`) is logging in on your behalf (rather than asking you to type a password). **Note:** If you had a GitHub account before, you may have used a password-based authentication. This is no longer supported, so you also need to follow the steps below! To create your github Personal Access Token, do the following: 1. Open [your github profile settings](https://github.com/settings/profile) by clicking on your profile icon in the top-right. Then, click **Settings**, like this:  2. In the page that opens, scroll down to the very bottom left and click on **Developer Settings**, which looks like this:  3. In the Developer Settings page, look at the sidebar on the left and click on **Personal Access Tokens** > **Tokens (classic)**, like in the red box below:  4. After clicking on **Token (classic)**, you should see the following screen. Click on **Generate new token** > **Generate new token (classic)**. <u>Be sure to pick the **classic** token!</u>  5. Then, you should see a page that looks like the image below. On this page, **fill in all of the following options**, as shown in the image: - **Name**: This is the name of your token--you can name it whatever you want (eg. "cs200"). - **Expiration**: Select "**No expiration**". You can ignore the warning from Github. - **Select scopes**: Select the "**repo**" option. This will check several other boxes under "repo".  7. Take a moment to **double-check that you have filled in all the settings** as on the figure, then click **Generate Token**. After you generate your token, you should see a page like this:  9. Your token is a super-secret value like a password--you'll enter it when cloning repositories. **Copy this token** and save it somewhere safe so you can access it later. 10. One final step: we can configure `git` to remember your token the first time you clone a repo (you'll do this later), that way you hopefully won't need to enter it more than once. To do this, **enter the following in your terminal**: ``` git config --global credential.helper store ``` Once again, this command won't produce any output. Great job! :tada: You should be all set for authenticating your Github account for this class. Now you're ready to clone repositories! If you're reading this guide for the first time (eg. HW0), take a look at the terminology in the next section, then go back to HW0 to continue with your IDE setup. You'll use `git` again to before you start running code! :sunglasses: <!-- Every time you try to clone / push to GitHub it will ask for your password, but what it’s actually looking for is your access token. This gets really annoying. We’d recommend configuring your computer to do this automatically. :::warning **Important:** you can save yourself a lot of future pain by configuring your `git` to save your access token so you don't need to enter it every time. To do this, enter the following in your terminal: ``` git config --global user.password "<access token>"` ``` where `<access token>` is replaced by the access token you just created (**without the `<>` brackets**) The first time you clone an assignment after following these steps you may be prompted for your GitHub username and password (this will be your personal access token). Please enter these and you should be all set! ::: --> # **Git terminology** Before you start using git, here is some important GitHub terminology you should familiarize yourself with: - **Repository** → a GitHub repository – or repo for short – is what a project on GitHub is called. Each time you accept an assignment for CS0200 by clicking on the assignment link, GitHub will create a repository for you for that project. - **Commit** → The cool thing about GitHub is that it can keep track of all of the versions of your project as you edit them. Each project “version” is called a commit. It is basically a snapshot of your project at a moment in time, and it is up to you to create commits when you reach points in your project that you do not want to lose. (Your project will be saved on your local machine, but in order to save a snapshot on your GitHub, you must create a commit and push it to your GitHub). It is good practice to create commits regularly so if something gets messed up while you are coding, you will have old versions to look back at stored on your GitHub repository. The next few sections describe some common tasks you'll do using `git`--the other course documentation will tell you when you need these, but remember that they're here in case you need them. :::info <h2 style="margin-top:0.2em; padding-top:0;"> More git resources</h2> For more info about git, we recommend checking out the following links: - **[Git - The Simple Guide](https://rogerdudler.github.io/git-guide/)**: a quick and dirty introduction - **[Harvard CS61 intro to git](https://cs61.seas.harvard.edu/site/ref/git/)**: a nice pictoral reference - **[Git handbook](https://guides.github.com/introduction/git-handbook/)**: an in-depth introduction ::: # Common git tasks This section outlines some common tasks for working with git. As you work on other assignments, we'll refer you to these sections as you need them: - **[How to clone a git repository?](#Cloning-a-git-repository)**: you'll do this once for every project - **[How to push your code to Github?](#How-do-I-push-my-code-to-Github)**: you can do this to save your work on Github, and to collaborate with others on the partner projects - [How to create a Personal Authentication Token?](#Creating-your-Github-access-token): you've already done this, but look here if you need to create another token ## Cloning a git repository Cloning a repository is how you download code to your computer. Depending on the assignment, there are two ways we might give you code to run, which changes how you will clone it: - For **Homework/Project/Lab stencils**, we will give you a **Github Invites link** (eg. `https://gh-invites.cs.brown.edu/<something>`).  To use these, see [**Accepting an Assignment on GitHub Invites**](#Accepting-an-Assignment-on-GitHub-Invites) - For **HW0, lecture code, or other examples**, we will directly provide a direct **Github Repository URL** (`eg. https://github.com/<something>`).  To use these, see **[Cloning from a Repository URL](#Cloning-a-repository-by-URL)**. ## **Accepting an Assignment on GitHub Invites** Github Invites (gh-invites) allow us to set up a unique repository to hold your code for an assignment or project.  To use it: 1. Accept the assignment on GitHub Invites by following the link on the handout and clicking the **“Accept this assignment”** green button, which should look like this (if you get an error, see [here](#repository-join-issue)):  2. Github will now create your repo–wait a few seconds and refresh the page.   When it’s done, you should see a link to your shiny new Github repository (like the example below), **click this link to view it!**    This link will open the main view of your repository on Github.  Next, we need to download (or clone, in git terms) the repository to our system:  to do this, see the next section.   ## **Cloning a repository by URL** Once we have a link to a repository, you can download it to your computer by “cloning” the repository into your CS200 folder with git.  To do this: 1. If you have not done so already, open the repository link in your browser.   2. On the Github page, click the green **“Code”** button and **click the copy button** to copy the link, like this:  ### **Getting to your CS200 folder** To clone the repo, we’ll need to use the terminal to browse to your CS200 folder and run git to download the code.  If you’re new with using a terminal, that’s okay!  Follow the steps below for a step-by-step guide.  Even if you’re more comfortable using a terminal, skim all of these instructions to make sure you understand the process–you might learn some useful shortcuts! 1. First, open the terminal on your computer: 1. **On Mac**: Go to **Applications** > **_Utilities_** > open **Terminal** - (Alternatively, you can open _Spotlight Search_ (keyboard shortcut is “Command+Space’’), search for “terminal”, and open the first application listed) 2. **On Windows**:  Open the Search bar,  enter “command prompt”, and click the first application listed :::info <h4 style="margin-top:0;"> Quick intro to terminals</h4> Just like when you browse folders in a window on your computer, in a terminal, there’s a concept of a current “working directory”, which is the folder where the terminal is “looking” at one time.  The working directory is usually displayed in the terminal’s _prompt_, which is the line where you enter commands.  To see the current working directory, enter the command `pwd`, like this:  Here, the working directory is the user `deemer`’s Desktop folder.  Another way to write this is `~/Desktop`, where `~` is shorthand for a user’s home folder.   ::: 2. Next, we need to navigate to our CS200 folder in the terminal.  There a few ways to do this--use whichever you feel most comfortable: <details><summary><b><u>Shortcut method (Mac)</u></b></summary> 1. Outside your terminal, open up your CS200 folder in Finder (the standard file/folder browser on Mac) 2. Drag the Finder window onto the Terminal icon on your dock (like the figure below).  This should open a terminal already pointing to your CS200 folder!  Pretty awesome, right??  😎 (If this doesn’t work for you, just go with the classic method.)  </details> <details><summary><b><u>Shortcut method (Windows)</u></b></summary> 1. Outside your terminal, open up your CS200 folder the way you’d normally search for a file 2. Inside the folder, **hold down Shift and Right Click** in the blank area in the folder view 3. In the menu that opens, click “**Open PowerShell window here**”.  (PowerShell is another terminal program inside Windows, similar to command prompt.)   &#x20;    If this method doesn’t work for you, just try the Classic method.   </details> <details><summary><b><u>Classic Method</u></b></summary> 1. In your terminal, use the `cd` command to enter into your CS200 folder.  The command for this will depend on where your CS200 folder is located on your computer–here’s what it should look like based on the folder locations we’ve recommended, but you can adjust it if you picked a different spot: - **Mac (CS200 folder on Desktop)**:  `cd ~/Desktop/CS200` or `cd "/Users/your-name-on-mac-here/Desktop/CS200"` - **Windows (CS200 folder on C: drive)**: `cd C:\CS200`  For more information on using terminal commands, take a look at our [Terminal Guide](https://docs.google.com/document/d/1kZ7AfOhUkZW1zqL7KWfEGuWvuyQZfPTK6x4jvCGFYlY/edit?usp=sharing), which describes `cd` and other commands in more detail.   At this stage, you should now have a terminal open to your CS200 directory!  Now we can finally clone the repository.   </details> ### **Cloning the repository with git** Next, you can download the repository to your computer–in git, this is called “cloning” the repository.  To do this: 1. Enter the following command using the [link you copied from Github](#Cloning-a-repository-by-URL). \ &#x20;`git clone <pasted link>` (without the “`<>`” brackets) 2. If you are prompted to log in, enter the following: - **Username**: Enter your **Github** username (*not* your Brown username) - **Password**: Paste in your **[Github Personal Access Token](#Creating-your-Github-access-token)** (eg. `ghp_XXXX...`). If you don't have one, see [these instructions](#Creating-your-Github-access-token). (**Note: you won't see the password in the terminal as you paste/type it**--this is normal, just paste and press enter.) After you log in successfully, you should see output something like this: ``` Cloning into '<name of repository>'... remote: Enumerating objects: 39, done. remote: Counting objects: 100% (39/39), done. remote: Compressing objects: 100% (33/33), done. remote: Total 39 (delta 8), reused 37 (delta 6), pack-reused 0 Receiving objects: 100% (39/39), 372.97 KiB | 6.32 MiB/s, done. Resolving deltas: 100% (8/8), done. ``` 2. If your output looks like this, your repository was cloned successfully, yay! If you see an error saying `Forbidden` or `Access denied`, make sure you are using the Github Access Token you created Once you have cloned the repository, you should now see a folder in your CS200 with the same name as the repository you cloned.  This is where the code lives! To continue working with the code, you'll need to open the repository--see the stencil setup guides for the language you'll be using: - For **Java** code, **[look here](https://docs.cs200.io/s/java-stencil-setup-guide#Opening-a-Stencil-in-IntelliJ)** for instructions on opening your code in IntelliJ - For **Python** code, **[look here](https://docs.cs200.io/s/python-stencil-setup-guide#Opening-a-Stencil-in-VSCode)** for instructions on opening your code in VSCode and setting up your environment <!-- Accepting assignments through GitHub Classroom can be a confusing process – do not fear, this section is here to help! Following these steps and accepting assignments should be a breeze (but if it’s not, please come to TA hours and we’ll be more than happy to help you troubleshoot). :::info **Note: Before the First Assignment**: Create a CS200 folder on your computer. This folder will hold all of your assignments for the rest of the semester. We recommend putting it on your Desktop (Mac) or the C Drive (Windows) for ease of access, but you can put it wherever makes sense for you! ::: **Follow these steps for every(!) assignment you accept through GitHub Classroom this semester starting on HW1a.** 1. Accept the assignment on GitHub Classroom by following the link on the handout and clicking the “Accept this assignment” green button 2. After a few seconds, refresh the GitHub page, you should see a link labeled “Access your Assignment” – click this link 3. Click the green “Code” button, which will open a dropdown that says “Clone”, then copy the link that is shown.  4. Open up the terminal (Mac) or command prompt (Windows) of your computer 5. Use the cd command to enter into the CS200 folder of your computer. (take a look at our [Terminal Guide](https://docs.google.com/document/d/1kZ7AfOhUkZW1zqL7KWfEGuWvuyQZfPTK6x4jvCGFYlY/edit?usp=sharing) for more info on what cd and other shell commands do) \ _If your CS200 folder is on your Desktop/C Drive, you can cd there as shown below:_ \ `cd ~/Desktop/CS200 or cd /Users/<yourName>/Desktop/CS200`(Mac)` cd C:\CS200 `(Windows) 6. Now you’ll have to paste the link from before in order to clone the repository locally. You should type `git clone <pasted link>` (without the “`<>`” brackets). For instance, you should see something like this: `Cloning into '<assignment#-username>'...` `remote: Enumerating objects: 53, done.` `remote: Counting objects: 100% (53/53), done.` `remote: Compressing objects: 100% (49/49), done.` `remote: Total 53 (delta 3), reused 52 (delta 3), pack-reused 0` `Receiving objects: 100% (53/53), 851.09 KiB | 3.49 MiB/s, done.` `Resolving deltas: 100% (3/3), done.` If you see the following output above, then Yay! You now have cloned the assignment onto your machine! To run it in IntelliJ you can go to `File > Open >` and navigate to your assignment folder (click the folder with the name `<assignment>-<github login>`)! However, you could run into authentication issues, such as the following output: `fatal: Authentication failed for '{github_link}'` If you are running into this issue, then look at the **How to Create a Personal Access Token** section below. --> ## Pushing your code to Github To save your work and submit it for grading, you will *commit* your changes to your repository's git history, and then *push* them to your repository on GitHub so they're stored online. Then, when you are ready to submit your work to gradescope (to run the autograder, or to submit), you can tell Gradescope to download your code from your Github repository and submit it for grading. The next few steps guide you in the process of submitting your code. ### Step 1: Open Your Terminal 1. In IntelliJ, **open a terminal** by clicking on the terminal icon in the lower-left corner (see the figure for a reference).  2. Take a look at your terminal's *prompt*: it should give the name of a directory (i.e., a folder on your computer), like the figure below. **This is the terminal's *working directory***: which acts like a "reference point" when you run terminal commands. Before continuing, **check that your terminal's working directory points to the same directory as your stencil** (e.g., something ending with `lab01-17-<yourusername>`). You'll see why this is important in the next step.  Now we're ready to start using git! ### Step 2: See What Changed Before you commit your code (and potentially send it to others), it's a good idea to review your work to see what will go into the history. 3. In your terminal (which we'd now say is "located in your stencil directory"), run the following command: ```shell git status ``` `git status` asks git to show you what files changed since the last *commit* (or, the latest version git knew about, which was when you cloned the repository). After working on the lab, you should see one or more files show up as "`Changes not staged for commit`" (for files that were in the stencil, but you changed) or "`Untracked files`" (for new files you created), like this:  :::info **Note:** If you can't see all the output in your terminal, try making the window a bit larger. ::: A few things to note here: - The exact number of files will depend on how far you got in the lab—as long as one file shows as changed, you can continue. - Look at the list of files: the list actually shows *paths* to files, relative to your working directory (i.e., your stencil folder). For example `sol/BSTTest.java` refers to `<stencil dir>/sol/BSTTest.java`. This is why the working directory was important! You'll see this idea of *relative* file paths come up a lot in later assignments. ### Step 3: Stage Your Changes 4. Because software projects can have a lot of files, we need to tell git which files you need to commit. This is called **staging your changes**. You can stage your changes using the command `git add`, like this (fill in each file that was changed, separated by spaces): ```shell # Idea: git add <file1> <file2> ... git add sol/BSTTest.java sol/Leaf.java <... other changed files ...> ``` :::success :rocket: **Awesome pro tip**: Are there a lot of files to type out? Want to do it faster??? Once you get a feel for `git add`, you can **add all your files at once**. To do this, run: ``` git add . ``` the `.` is a standard terminal shorthand to refer to the current directory. If you do this, be sure to run `git status` afterward (the next step) to make sure everything you want got added (and that there's nothing extra)! ::: :::warning **If you see a file `.idea/misc.xml`**: This file is part of IntelliJ's settings--we include a version in the stencil, but your IntelliJ might modify it and cause it to show up as changed. If this happens, you can `git add` the file like any other. (The autograder doesn't use these files, so it won't affect anything.) ::: 5. After you run `git add`, you shouldn't see any output in your terminal (with many terminal commands, "no news is good news"). **To see what changed, run `git status` again**, which should look like this:  `git status` should now show your changes as **staged**: this means they're ready to be committed. If you continue changing your files after this, you'll need to stage/commit them again. ### Step 4: Commit Your Changes 6. Now it's time to commit! (You got this!) To commit your changes, do the following: ```shell # Idea: git commit -m "<some message about what you did>" git commit -m "finished lab 1" ``` Committing your work **takes your staged changes and adds them to the history**: a git repository is actually a list of these changes! After committing, you should see a message summarizing the changes, like this:  :::info **Note:** Sometimes, if you add an exclamation point/punctuation at the end, you'll see "dquote>" which you can fix by just adding another closing quotation mark and hitting enter! Single quotes around your commit message (`git commit -m 'finished lab 1!'`) also avoid the issue. ::: ### Step 5: Push to GitHub 7. **Almost there**: now that you've committed your changes, you need to send them to your repository on GitHub: this is called **pushing your changes**. To push your code, run the following: ```shell git push origin main ``` This tells git to send your changes to the location where you cloned the repository (called `origin` by default) on the `main` branch. The details of these aren't important now, but if all goes well you should see output like the following, denoting that the push was successful:  Yay, your changes are now on GitHub! ### Step 6: Verify on GitHub 8. To see your changes online, **open up your stencil repository on GitHub** (go to [github.com](https://github.com) and look in the "Repositories" view). You should see the viewer show your latest commit message (like the figure), and if you browse around you should see your latest files!  Now that you can see your files on GitHub, you've successfully pushed your code! 😎 :::danger :warning: **WARNING**: If you are trying to submit your work on Gradescope, you're not done yet! Be sure to **submit on Gradescope** by providing a link to your Github repository. See here for instructions. Your work is not submitted for grading until your upload to Gradescope! ::: :::success **Git tips for the future** Now that you've had some practice with git's core features, there are some shortcuts you should know to make your life easier: - To quickly add all files at once without typing the names, run: `git add -A` - The output of `git status` is a good quick reference on how to add/remove files from the set of staged changes—if you need help on this, start there! For more info on git, see our [GitHub Guide](https://docs.cs200.io/s/github-guide)! ::: <!-- ### How do I push my code to Github? If you want more information on what the actual commands do, then go to the **Need to Know Commands** section that goes through the commands needed to `git push`. However, here is a step-by-step guide with pictures that allows you to push your code to Github. 1. After you have made some changes, navigate to your terminal at the bottom of IntelliJ/VSCode. Additionally, make sure that you are in the same directory as your project/homework/lab.  2. Next, type in the following command: `git add .` (make sure that there is a space between the `add` and the period). There should be no output after.  3. Next type in the following command: `git commit -m "message"` where the particular message is the message for your git commit. For example, since I edited my `AttributeNode` class in my Decision Tree project, I can type in the following commit message. Additionally, you can see the files that you have changed, the insertions that you made, and the deletions that you have made in the commit log.  4. Next type in your `git push` command. If you see the output below, then you have successfully pushed your code to Github.  5. If you want to check that your code got pushed, then click on the blue link that is highlighted below:  6. If you click on that link, that will take you to your Github repository and you will see your commit message on the files that you have changed.  --> ## Appendix: Helpful git commands | | | | :--------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | **Command** | **Explanation** | | `git clone <repo URL>` | Once you accept an assignment and your repo is created, click the green “Code” button and copy the link that is listed. That link is your repo URL. Then, in your terminal, type this command with the repo URL to make a folder with the code in your repo on your computer. The folder will be made in whichever directory you are currently in, so be sure to cd into your desired directory before running this command! | | `git add <file>` OR `git add -A` | This command is the first of 3 commands that you need to run when you are trying to get the code you wrote on your computer back up to GitHub. You must add the files that you want to update on GitHub. You can do this by running git add with one file specified at a time, or you can use `git add -A` to update all files (typically what is used when you want to save a snapshot of your current code). | | `git commit -m “<message>”` | Once you have added all of the desired files using git add, you are ready to commit these changes and save your snapshot to GitHub! This command is the 2nd of 3 commands you must run to get your code edits back up to GitHub. It creates the commit, or “snapshot” that we will soon send to GitHub. Instead of `<message>`, you should write something informative about what you’ve changed! | | `git push` | Now you’re ready to push the changes to GitHub! Running this command will send your commit to the online repository where your code is stored. This is the final of the 3 commands you will run to get your code back to GitHub! After running this, go on your GitHub repo and ensure that your updates were made! | | `git pull` | This command lets you pull any changes on this repository that are present on GitHub but not on your local machine. No need to worry about this for solo projects, but if you’re working on partner projects, pull before you begin working / after you commit and before you push in order to get all your partner’s changes! | | `git status` | This command lets you see which files have been changed since your most recent commit (i.e., the changes between the working tree and the index file) as well as paths in the working tree that are not being tracked by Git. The first are what you would commit by running `git commit`; the second and third are what you could commit by running `git add` before running `git commit`. | If you have any git problems, feel free to post on Ed! ## Dealing With Merge Conflicts This section of the guide is adapted from CS15's [debugging lab](https://hackmd.io/@Fall2024-CS15/HJKArBCsR) <3 When working with a partner and using GitHub, you may run into merge conflicts while updating the same file. For example, when one partner runs `git pull` to get the most up-to-date version of the code, they may encounter an error message like this: ``` (base) katieli@Katies-MacBook-Pro-1333 katieli1 % git pull hint: You have divergent branches and need to specify how to reconcile them. hint: You can do so by running one of the following commands sometime before hint: your next pull: hint: hint: git config pull.rebase false # merge hint: git config pull.rebase true # rebase hint: git config pull.ff only # fast-forward only hint: hint: You can replace "git config" with "git config --global" to set a default hint: preference for all repositories. You can also pass --rebase, --no-rebase, hint: or --ff-only on the command line to override the configured default per hint: invocation. fatal: Need to specify how to reconcile divergent branches. ``` If this happens, run `git config pull.rebase false` to attempt a merge. After you do this, you may get an error in your terminal that says you have a merge conflict. Merge conflicts generally arise when two people have changed the same lines in a file, or if one person deleted a file while another was modifying it. It’s important to know how to resolve these conflicts so you can continue to code and work. Your code will not compile and run if you have merge conflicts. You can easily see the files that have merge conflicts since IntelliJ will highlight them in a different color and put squiggly read lines under the file names. You’ll notice some strange characters on the file: ``` <<<<<<< HEAD [the code Partner B wrote] ======= [the code Partner A wrote] >>>>>>> 48ceadf56648d2736a68f88bde2d16390c4e6f87 (or some other long string) ``` Think of these as conflict markers. The code after `<<<<<<< HEAD` are changes that you made (`HEAD` represents the current commit you’re working on). The `=======` line acts as a divider. The code below this line and the `>>>>>>> [commit hash]` line are changes being brought in (that your partner made!), in this case from a different git commit `48ceadf56648d2736a68f88bde2d16390c4e6f87`. This long number is the commit hash. Think of it as a unique ID for each commit made on the repository. In order to resolve this conflict and have your code successfully compile, you should remove all of the lines in the conflict marker EXCEPT the lines that do what both you and your partner want. The first thing that we should do is communicate with our partner about which parts of the code we want to keep. Once we decide that, we can remove everything else. For example, if you decide that you want to keep Partner B's code, you can remove Partner A's code and all the conflict markers. Then, once only Partner B's code remains, you can commit and push the result to Github. ### How Can We Avoid Merge Conflicts? Here are some guidelines for reducing the number of merge conflicts you encounter. 1. Run `git pull` before you start modifying any code during your partner projects. This will get your local code up-to-date with the repository on GitHub before you start coding, thus avoiding the chance that you modify something locally that your partner has also changed – the basic cause of a merge conflict. 2. Add, commit, and push your code to GitHub as soon as you finish working on your project for a period of time. Make sure that your local code is always pushed to GitHub as soon as you’ve made any changes – even if it’s just two lines. This is so that your partner can pull those changes when they start working, and the code on both of your computers will match each other. 3. Commit any changes you have before pulling. Git won’t let you pull changes from the remote if you have changes in your code that you haven’t committed. 4. Communicate! Communication with your partner is key to reducing the number of merge conflicts you encounter. *** _Please let us know if you find any mistakes, inconsistencies, or confusing language in this or any other CSCI0200 document by filling out the_ [_anonymous feedback form_](https://docs.google.com/forms/d/e/1FAIpQLScDfGq8uaR2zXSc9wZTA83kfmM8N9UATB0RU0cGMfvJnmL5lQ/viewform)_._