> ## 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.
# Working with Git
> Practical Git workflows for Calcs.com development
## Checking Out
### Working with Existing Branches/Changing Between Branches
Remember, we never make changes directly to the Master branch, but we create branches off Master to do our work. We can swap between Master and feature branches by using `git checkout {branchName}`.
**Examples:**
* `git checkout master` - Move to the Master branch
* `git checkout retainingWallsUSA` - Move to the retaining walls branch
When you swap between branches, you should `git pull` before and after you swap to ensure you have the latest copy of everything on your local PC.
**Command line workflow:**
```bash theme={null}
git pull
git checkout retainingWallsUSA
git pull
```
You don't explicitly need to pull beforehand, however if it's been a while since you used Github or you have never checked this branch out before, this can ensure VScode knows what you are talking about when you try to check out the new branch. It also means you can use tab completion to type things faster!
To avoid issues when changing branches or creating new branches, we recommend regularly going back to master.
### Creating a New Branch
If you are not looking at someone else's work or swapping into a branch you've already been working on, you will need to create a new branch.
You should *always* create a new branch from Master, not from another feature branch (no branches off branches!).
To ensure this, and to avoid headaches later because you were working off old data:
1. Checkout master: `git checkout master`
2. Pull master: `git pull`
3. Create your new branch
Creating a new branch is very similar to checking out an existing branch, with one small exception. We add a `-b` to our checkout command to tell Git it's new:
```bash theme={null}
git checkout master
git pull
git checkout -b {newbranchName}
```
## Making Changes and Submitting Your Work
### Staging & Committing
Once you have successfully checked out a new or existing branch, you'll be ready to start making changes. Provided your VScode and Git have been set up correctly, as you make changes, they will appear in the sidebar under 'Changes'.
Until you stage, commit, and push these changes, *they are only on your PC*. This makes committing and pushing regularly a very important habit.
#### Understanding Commits
Github thinks of version control in terms of **Commits** - these are bundles of changes, with a reason behind them. Each branch can have multiple commits, all it means is we are grouping (Staging) each set of changes we make, and naming them.
#### How to Stage Changes
To stage some changes, you can either:
* Click the + icon next to the file you want to stage
* Right click the file and click 'Stage Changes'
Do this for each file you want to stage.
#### How to Commit
As you stage your changes, they will move into a 'Staged Changes' dropdown, meaning they are ready to be **Committed**.
To commit:
1. Enter a message in the dialog box above describing your changes (e.g., `Amended calc count in trusted by section`)
2. Click Ctrl + Enter (or Cmd + Enter on Mac) to submit and commit your changes
You can also right click and Unstage changes if you make a mistake, or click 'Discard Changes' if you want to irreversibly delete the new changes you've made and go back to the version you most recently committed.
Your work is not yet on Github after committing! Once you commit, you need to `git push` to send it upstream to the server.
#### Pushing to Github
If you are working on a new branch that has never been pushed before, you will get a fatal error (this is fine). Just copy and paste the message into the terminal and it will push properly.
Once you have successfully pushed your work, you can either:
* Keep working and create new changes and commits
* Change to another branch without fear of issues
### Submitting Your Work Back to Master (Pull Requests)
When you're ready to submit your work back to master, you need to create a pull request. We will cover that in volume two of our git for dummies series when chris isn't tired and thirsty.
## Common Issues
* Merge conflict
* Git reset/bad commit
* Can't find branch (git fetch)
* Bad line endings (bad git for windows setup)
* Branching off a branch