# Updating Hog to a Newer Release

This guide will help you update Hog to your desired version. It assumes you already have a repository managed with Hog and hosted on GitLab or GitHub.

## Preparation

On your project's website, create a new branch starting from `master` and open a merge/pull request for your changes.

:::{note}
If you are already working on a branch in your HDL repository, you can update Hog within that branch.
(Alternatively, you can create a new branch locally and open the merge request on the website later.)
:::

## Updating the Hog Submodule

Check out your branch and navigate to the `Hog` directory. To update Hog to the latest version, run:

```bash
cd Hog
git checkout master
git pull
```

To verify the version you have checked out, use:

```bash
git describe
```

You should see something like `HogYYYY.n` (e.g., `Hog2020.1`) or `vX.Y.Z` (e.g., `v1.2.3`).

If you want to update to a specific version, visit the [Hog releases page](https://gitlab.com/hog-cern/Hog/-/releases), choose your desired version (e.g., `v1.2.3`), and run:

```bash
cd Hog
git checkout v1.2.3
```

## Updating the GitLab CI Configuration

If your project uses GitLab CI, you need to update your `.gitlab-ci.yml` file to reference the new Hog version. If you are not using GitLab CI, you can skip this step.

Go back to your repository root and edit `.gitlab-ci.yml` with your preferred editor:

```bash
cd ..
vim .gitlab-ci.yml
```

At the beginning of the file, in the `include` section, you will see a reference similar to:

```yaml
include:
  - project: 'hog/Hog'
    file: '/hog.yml'
    ref: 'vA.B.C'
```


Update the `ref` field to match the new version you have checked out:

```yaml
include:
  - project: 'hog/Hog'
    file: '/hog.yml'
    ref: 'vX.Y.Z'
```

If you are using the dynamic CI, the `include` section will look like:

```yaml
include:
  - project: 'hog/Hog'
    file: '/hog-dynamic.yml'
    ref: 'vX.Y.Z'
```

Save and close the file.

## Finalizing the Update

Add the updated files (`Hog` submodule and `.gitlab-ci.yml`), commit, and push your changes:

```bash
git add .gitlab-ci.yml Hog
git commit -m "Update Hog to vX.Y.Z"
git push
```

Finally, go to your project's GitLab/GitHub website, open a merge request for your branch (if you haven't already), and merge it once the CI passes.