# Git-based workflows

https://www.sanity.io/learn/course/content-driven-web-application-foundations/git-based-workflows.md

Version control, collaborate on, and deploy your Next.js application by storing it in a Git repository.

If you've built modern web applications with a developer team, you may already be familiar with Git and GitHub. This lesson explains the basics for anyone new to Git-based version control or unfamiliar with branch-based workflows for collaborating with other developers on a project. 

A strategy for safely iterating on a project is the key to working confidently on updates, new features, and improvements.

1. If you're entirely new to Git, Epic Web has a [free Git Fundamentals tutorial](https://www.epicweb.dev/tutorials/git-fundamentals), which will get you up to speed with the basics.

## Create a remote repository

For this lesson, you will need an account on GitHub. You could use other Git providers if you choose, but you would need to adapt the tasks in this lesson accordingly.

Currently, your Next.js application is only available on your machine. It must be deployed on Vercel's hosting to be shared with the world. To do that, there is an intermediary step of uploading your files to a Git repository.

1. **Create or log in** to your [GitHub account](https://github.com/)
2. From the GitHub dashboard, click "New" to create a new repository.

![GitHub dashboard for creating a new repository](https://cdn.sanity.io/images/3do82whm/next/473b6851f9d2f67b32341802df97be05a5529b49-2144x1388.png)

You can give your repository any name. You can also choose to make it Public or Private.

On the next screen, you should see instructions for "quick setup" and commands to run for either a new or existing repository. When you ran `create-next-app`, it initialized one automatically, so you can follow the instructions "... or push an existing repository from the command line."

![GitHub instructions for pushing an existing repository](https://cdn.sanity.io/images/3do82whm/next/7c68715dc8e1aba960da361ba0891f46998033a0-2144x1388.png)

The code for my repository looks like this above, but the first line will differ from yours as it has your account and repository name.

1. **Run** the command to push an existing repository
2. **Refresh** the page, and you should now see _most_ of your local files in your remote GitHub repository

![Missing alt text](https://cdn.sanity.io/images/3do82whm/next/2483919ccd3687615dc0ae9ee4ac739317a4632d-2144x1388.png)

## Updating remote

Currently, the remote repository only contains the **original** files created when you ran `create-next-app`, not any Sanity-related files you created or changed after that. 

You must "commit" those files locally and push them to the `main` branch.

1. **Run** the following from your terminal to add the remaining local files to `main`

```sh
git add .
git commit -m "add sanity files"
git push origin main
```

Refresh your repository on GitHub, and you should see the additional files.

1. Pushing directly to the `main` branch like this is _okay_ this once, but it's not great for tracking the history of changes and is _terrible_ for working collaboratively with others. Continuing to do this will likely result in problems.

Before connecting your repository to Vercel to host your application, it's good to have a strategy **now** for working locally on new features and updating remotely.

## Workflow for making changes

Your local files are now stored remotely on GitHub as a point-in-time snapshot. At this moment, your local and remote files are in sync. 

Each time you work locally, you will need to update your remote Git repository to update your hosted Next.js application.

Most commonly, this would be done by: 

1. creating a "branch" off of the `main` branch
2. committing changes to local files
3. pushing that branch to remote
4. creating a "pull request" from the branch to `main`
5. merging those changes into the `main` branch remotely
6. updating your `main` branch locally

Let's try this now.

1. **Run** the following command to create a new branch named `update-readme`

```sh
git checkout -b update-readme
```

1. **Update** the `README.md` with the following:

```markdown
# Sanity and Next.js

This is a [Sanity.io](https://sanity.io) and [Next.js](https://nextjs.org) project created following a Course on [Sanity Learn](https://sanity.io/learn).

## Getting Started

First, run the development server:

```bash
npm run dev
```

- Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
- Open [http://localhost:3000/studio](http://localhost:3000/studio) to edit content.
```

1. Keeping the readme of a project up to date with helpful notes for new developers joining the project in the future is good practice.

1. **Run** this command to check the current local status of all files:

```sh
git status
```

You should see the following, which shows us that the `README.md` file has been modified, but nothing is yet staged for a commit:

```text
On branch update-readme
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")
```

1. **Run** the following commands to add all changed files and create a commit message:

```text
git add .
git commit -m "update readme"
```

1. **Run** this command to push the local state of this branch to the remote:

```text
git push -u origin update-readme
```

You should get a confirmation in the terminal that it was successfully completed, and a URL to visit to create a pull request.

1. **Create** a pull request: On GitHub, in your repository, go to the "Pull requests" tab and create a new one to merge `update-readme` into `main`.

You should then see a page just like this: 

![Missing alt text](https://cdn.sanity.io/images/3do82whm/next/c0935c0bba2a40b969b327c0d4be1bfe290e5327-2144x1388.png)

Creating a "PR" is an essential step in your future workflow for your fellow developers and content creators. 

On a developer team, you may have a colleague review and approve your changes before they are merged.

For your authors, and once you have connected this repository to Vercel, this will create a "Preview build" of your Next.js application so that you can see the results of your latest round of changes in the hosted environment _before_ merging.

Preview builds are great for collaboration so you can share updated versions of the application without affecting the production environment. This is useful for testing new front end features as well as showing authors any updated Sanity Studio configuration.

From this page, you can also see an overview of the changes being made. In this PR, it is only one file with a few lines changed.

1. Scroll to the bottom and click "Merge pull request" and "Confirm merge."

Now, the `main` branch has the latest version of your code, but only remotely. In your local development environment, the `main` branch is out of date.

1. **Run** the following in the terminal to switch back to the main branch:

```text
git checkout main
```

If you open `README.md` now you'll notice it has reverted to the previous version, because this is what it looked like when you were last **locally** working on `main`.

1. **Run** the following in the terminal to pull the latest version of main from remote:

```text
git pull origin main
```

Now `README.md` is as you had it before, and both your local and remote versions of the `main` branch are up to date.

You now have a _basic_ version of a Git workflow to follow. Once other developers are working on the same repository, they'll all have their branches and pull requests which you may be involved in reviewing. You'll also need to update your local version of the `main` branch before creating any new branches.

1. Larger teams may benefit from even more structure around Git workflows. [Conventional commits](https://www.conventionalcommits.org/) is one commonly implemented pattern.

Your code is now hosted remotely, but your web application is not. With this setup, it's time to go live. Let's connect Vercel to your repository in the next lesson.