Git introduction for PISM developers¶
Recommended Git configuration¶
Set name and e-mail address:
git config --global user.name "John Doe" git config --global user.email firstname.lastname@example.org
Do not push local branches nonexistent on upstream by default:
git config --global push.default simple
Set an editor to use when writing commit messages. For example, run
git config --global core.editor vi
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.
When starting work on a new feature make sure to start from the
git checkout dev
When working on a bug fix for the current (released) PISM version, start from
git checkout main
See Git branches for more.
Next, create and switch to a new branch:
git checkout -b <user-name>/<short-description>
<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.
git checkout -b ckhroulev/energy-balance
Work on the code, documentation, etc.
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
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
maindirectly unless you know what you are doing.
If you started your branch from
devand need to use a feature that was added to
devsince then you can run
git merge dev
to “merge” the
devbranch into your branch.
Please do not merge
devinto 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.