Git introduction for PISM developers

Working on a new branch

This section summarizes Git commands used in a typical development workflow. A good Git GUI can save you from having to type these commands yourself but one should still know them.

  1. When starting work on a new feature make sure to start from the dev branch:

    git checkout dev

    When working on a bug fix for the current (released) PISM version, start from main instead:

    git checkout main

    See Git branches for more.

  2. Next, create and switch to a new branch:

    git checkout -b <user-name>/<short-description>

    where <user-name> is your GitHub user name and <short-description> is a short (two or three words) description of the topic you intend to work on.

    For example:

    git checkout -b ckhroulev/energy-balance
  3. Work on the code, documentation, etc.

  4. Inspect changes:

    git status
  5. Commit changes:

    • To commit all changes to files that are already in the repository:

      git commit -a
    • To commit particular files

      git commit file1 file2 ...
    • To add new files that are to be committed:

      git add file1 file2 ...
      git commit
  6. Push changes to GitHub:

    git push -u origin ckhroulev/energy-balance

    Push changes to your own branch or other branches dedicated to a topic you may be sharing with your collaborators.


    Do not push to dev or main directly unless you know what you are doing.

  7. If you started your branch from dev and need to use a feature that was added to dev since then you can run

    git merge dev

    to “merge” the dev branch into your branch.


    Please do not merge dev into your branch unless you need to: doing it too often makes the development history (git log) more confusing and less useful.

Writing better commit messages

Every commit should be accompanied by a meaningful message.

A commit message consists of a short one-line summary followed by a blank line and a free-form body of the message.

The summary should be capitalized, use the imperative mood, and should not end in a period.

The body of a commit message should explain what changes were made and why (but not how).

If a commit addresses a GitHub issue, please include the issue title and number in the body. Summarize the issue if its title is not descriptive enough.

Previous Up Next