Git
Git is the version control system (VCS) that is responsible for tracking all changes done to the code base. Git is a distributed version control system that tracks changes in any set of computer files, and allows for collaborative development of source code and documentation. We use Git as a service through GitHub. See GitHub Docs for more information about GitHub and how to get started.
If you do not want to work with files locally, GitHub lets you complete many Git-related actions directly in the browser, including:
Setting up Git
Go to git-scm.com to download the appropriate git client unless it is already installed on your system.
To verify that git is installed, you can run:
git --version
See GitHub Docs - Set up Git for detailed instructions.
Using Git
Git is a powerful tool that can be used in many ways. We recommend the following resources:
- Introduction to git - GitHub - About git
- How to get out of git trouble Oh shit, Git!?!
Below we will describe the most commonly used commands and scenarios when working with git.
In the following sections we use the syntax <some text> where you should fill in your own values, such as:
- <change type>: conventional commits change types such as feat, fix, docs, test, chore, refactor, etc.
- <issue number>: the GitHub Issue Number that you are solving. This may be omitted if you are fixing something tiny.
- <description>: a short summary of the code changes, e.g., fix: array parsing issue when multiple spaces were contained in string.
Cloning a git repository
Navigate to the location where you want to store the code, and clone the repository:
git clone git@github.com:equinor/ecalc.git
This will create a local copy of a project that already exists remotely. The copy will be stored in a sub-folder, with the same name as the repository, ecalc/.
Tell Git who you are
git config --global user.name "My name"
git config --global user.email example@email.com
This is what will show in the git log when you make changes.
Create your own branch
In order to create a new local branch and switch to it:
git checkout -b <type of change>/<issue number>-<description>
for new versions of git you may also use the more intuitive.
git switch -c <type of change>/<issue number>-<description>
Switch between existing branches
git checkout <branch name>
Fetch changes from GitHub
git pull
This will update the local branch you are currently in, with changes done in GitHub.
git push --set-upstream origin <change type>/<issue number>-<description>
Send your changes to GitHub
git push
This will update the remove repository on GitHub. If it is the first time for a new branch you will also have to tell git that you are creating a new remote branch by using the command:
Check status of changes
List the files you have changed and those you still need to add or commit:
git status
Add files
Add new or changed files
git add <filename>
or adding everything in and below your working directory
git add .
Commit changes
Commit any files you've added with git add, and also commit any files you've changed since then:
git commit -m "<change type>: <description"
This will save a snapshot to the project history and completes the change-tracking process. Anything that has been previously staged with git add will become a part of the snapshot with git commit.
Send changes to GitHub
In order to send changes back to GitHub, you will use the following command:
git commit -m "<change type>: <description"
Workflow examples
Pull Requests
For Equinor internal developers you are welcome to open a Pull Request directly in the ecalc repository.
Here's a quick guide:
- Clone the project to your machine:
git clone git@github.com:equinor/ecalc.git - Create a branch locally with a succinct but descriptive name and prefixed with change type.
git checkout -b <change type>/<issue number>-<description of change> - Add the changed files
git add <path to changed file(s)> - Commit your changes using the conventional commits formatting for the commit messages.
git commit -m "<change type>: <description>" - If your changes are in conflict with changes done by other, then you need to rebase and solve the change conflicts. This also ensures your code is running on the latest available code.
git fetch
git rebase origin/main - Push changes to GitHub
git push --set-upstream origin <change type>/<issue number>-<description> - You can now Create a Pull Request
Fork the repository
For external developers, you will contribute to the project through forking.
Here's a quick guide:
- Create your own fork of the repository
- Clone the project to your machine
git clone git@github.com:equinor/ecalc.git - To keep track of the original repository add another remote named upstream
git remote add upstream git@github.com:equinor/template-fastapi-react.git - Create a branch locally with a succinct but descriptive name and prefixed with change type.
git checkout -b <change type>/<issue number>-<description> - Make the changes in the created branch.
- Add and run tests for your changes if needed (we only take pull requests with passing tests).
- Add the changed files
git add <path to changed file(s)> - Commit your changes using the conventional commits formatting for the commit messages.
git commit -m "<change type>: <description>" - Before you send the pull request, be sure to rebase onto the upstream source. This ensures your code is running on the latest available code.
git fetch upstream
git rebase upstream/main - Push to your fork.
git push origin feature/my-new-feature - Submit a [Pull Request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests creating-a-pull-request-from-a-fork). Please provide us with some explanation of why you made the changes you made. For new features make sure to explain a standard use case to us.
That's it... thank you for your contribution!
After your pull request is merged, you can safely delete your branch.