> ## Documentation Index
> Fetch the complete documentation index at: https://calcs.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Usage Guide

> Common Git tasks and workflows for Calcs.com development

## Basics for Calcs.com

We use git to manage all of our development work for Calcs.com. You should reference any of the dozens of git tutorials Google will find you about git if you're completely unfamiliar ([like this from git-scm](https://git-scm.com/book/en/v1/Getting-Started)).

However, these are going to be the common tasks you'll want to do with git on your computer. All of these commands should either be run from VSCode itself, or from the dev-environment directory in a local terminal on your computer.

## Common Tasks

### Checkout an Existing Branch

You will always be on a "branch" - which is a current set of code for Calcs.com. Each branch is either a new segment of work or 'master', which is the code behind what's currently in review (on preprod.calcs.com).

<Tabs>
  <Tab title="VSCode">
    1. Go to the git view (left sidebar, third icon down, Y-shaped)
    2. Under "Source Control Providers", you'll see "dev-environment" and the current branch
    3. Click on that branch name and select a new branch to change it
    4. Click the circular arrow to the right of the branch name to get the latest work
  </Tab>

  <Tab title="GitHub Desktop">
    1. Make sure "dev-environment" is selected under "Current Repository" (upper left)
    2. Use the "Current Branch" dropdown to select any other branch
  </Tab>

  <Tab title="Terminal">
    ```bash theme={null}
    git checkout branchName
    ```
  </Tab>
</Tabs>

### Create a New Branch

Any time you start on a task which will make a complete work product, such as a single new sheet, or one major change to an existing sheet, you'll create a new branch.

<Tabs>
  <Tab title="VSCode">
    1. In the git view, click on the current branch name
    2. Change to 'master', then press the circular arrow (VITAL - ensures you're starting from the most recent code)
    3. Click on the branch name again
    4. At the top of the list, click "Create a new branch"
    5. Type in the name of your new branch, press 'Enter'
    6. Click the cloud button to the right of the branch name to create the branch on the server
  </Tab>

  <Tab title="GitHub Desktop">
    1. In the "Current Branch" dropdown, click "New Branch"
    2. Enter a name for your new branch
    3. Make sure "master" is selected under "Create branch based on..."
    4. Click "Create Branch"
  </Tab>

  <Tab title="Terminal">
    ```bash theme={null}
    git checkout master
    git pull
    git checkout -b yourNewBranchName
    git push --set-upstream origin yourNewBranchName
    ```
  </Tab>
</Tabs>

### Commit a Change

After you change a few things and save your file, you should 'commit' your changes.

<Tabs>
  <Tab title="VSCode">
    1. In the git view, click the "+" sign on each file you want to commit to stage your changes
    2. Write a description of your commit in the "Message" line at the top
    3. Click the checkmark next to the branch name, or press Alt+Enter (⌘+Enter on Mac)
  </Tab>

  <Tab title="GitHub Desktop">
    1. Check the files you want to commit in the "changed files" list
    2. Enter a description in the "Summary (required)" box
    3. Click "Commit to \[branchName]"
  </Tab>

  <Tab title="Terminal">
    ```bash theme={null}
    git commit filename.json "message"
    ```
  </Tab>
</Tabs>

<Note>
  Nothing gets sent to the server when you commit. You need to push your changes!
</Note>

### Push Your Changes to the Server

Actually send your work to the server. This becomes both a backup and helps keep track of everything.

<Tabs>
  <Tab title="VSCode">
    Click the circular arrow icon to the right of the branch name under "Source Control Providers". This will 'push' all your commits to the server and 'pull' anyone else's updates.
  </Tab>

  <Tab title="GitHub Desktop">
    Click "Fetch Origin" or "Push Changes" in the upper right. You may need to click twice to both 'pull' updates and 'push' your changes.
  </Tab>

  <Tab title="Terminal">
    ```bash theme={null}
    git push
    ```
  </Tab>
</Tabs>

### Create a Pull Request (PR)

When you think you're done with all of the work in your current branch, you should create a pull request to get your changes pulled into the master branch.

**On github.com only:**

1. Log in to [github.com](http://github.com/)
2. Click on "Pull requests" (or use [this direct link](https://github.com/ClearCalcs/dev-environment/pulls))
3. Click "New Pull Request" and select your branch
4. Assign someone else as a "Reviewer" (on the right-hand panel)
5. Click submit!

## Other Things

### Dealing with Unexpected Issues

Tutorial loom videos on an issue that the buildkite result shows "Building Standard" changed, e.g. "building standard NZ➝ AU":

* [Video 1](https://clearcalcs.slack.com/archives/CBS2438UE/p1662513981238029?thread_ts=1662475413.461899\&cid=CBS2438UE)
* [Video 2](https://clearcalcs.slack.com/files/UC7MZ5XEY/F04ND02NDGW/screenshare_-_2023-02-08_4_03_51_pm.webm)