tgit-introduction.rst - pism - [fork] customized build of PISM, the parallel ice sheet model (tillflux branch)
(HTM) git clone git://src.adamsgaard.dk/pism
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) LICENSE
---
tgit-introduction.rst (3443B)
---
1 .. include:: ../global.txt
2
3 .. default-role:: literal
4
5 .. _sec-git-introduction:
6
7 Git introduction for PISM developers
8 ====================================
9
10 .. _sec-git-configuration:
11
12 Recommended Git configuration
13 -----------------------------
14
15 Set name and e-mail address:
16
17 .. code-block:: bash
18
19 git config --global user.name "John Doe"
20 git config --global user.email johndoe@example.com
21
22 Do not push local branches nonexistent on upstream by default:
23
24 .. code-block:: bash
25
26 git config --global push.default simple
27
28 Set an editor to use when writing commit messages. For example, run
29
30 .. code-block:: bash
31
32 git config --global core.editor vi
33
34 to use `vi`.
35
36 .. _sec-new-feature-branch:
37
38 Working on a new branch
39 -----------------------
40
41 This section summarizes Git commands used in a typical development workflow. A good Git
42 GUI can save you from having to type these commands yourself but one should still know
43 them.
44
45 #. When starting work on a new feature make sure to start from the `dev` branch:
46
47 .. code-block:: bash
48
49 git checkout dev
50
51 When working on a bug fix for the current (released) PISM version, start from `master`
52 instead:
53
54 .. code-block:: bash
55
56 git checkout master
57
58 See :ref:`sec-git-branches` for more.
59
60 #. Next, create and switch to a new branch:
61
62 .. code-block:: bash
63
64 git checkout -b <user-name>/<short-description>
65
66 where `<user-name>` is your GitHub user name and `<short-description>` is a short (two
67 or three words) description of the topic you intend to work on.
68
69 For example:
70
71 .. code-block:: bash
72
73 git checkout -b ckhroulev/energy-balance
74
75 #. Work on the code, documentation, etc.
76
77 #. Inspect changes:
78
79 .. code-block:: bash
80
81 git status
82
83 #. Commit changes:
84
85 - To commit all changes to files that are already in the repository:
86
87 .. code-block:: bash
88
89 git commit -a
90
91 - To commit particular files
92
93 .. code-block:: bash
94
95 git commit file1 file2 ...
96
97 - To add new files that are to be committed:
98
99 .. code-block:: bash
100
101 git add file1 file2 ...
102 git commit
103
104 #. Push changes to GitHub:
105
106 .. code-block:: bash
107
108 git push -u origin ckhroulev/energy-balance
109
110 Push changes to your own branch or other branches dedicated to a topic you may be
111 sharing with your collaborators.
112
113 .. note::
114
115 Do *not* push to `dev` or `master` directly unless you know what you are doing.
116
117 #. If you started your branch from `dev` and need to use a feature that was added to `dev`
118 since then you can run
119
120 .. code-block:: bash
121
122 git merge dev
123
124 to "merge" the `dev` branch into your branch.
125
126 .. note::
127
128 Please do not merge `dev` into your branch unless you need to: doing it too often
129 makes the development history (`git log`) more confusing and less useful.
130
131 .. _sec-better-commit-messages:
132
133 Writing better commit messages
134 ------------------------------
135
136 Every commit should be accompanied by a meaningful message.
137
138 A commit message consists of a short one-line summary followed by a blank line and a
139 free-form body of the message.
140
141 The summary should be capitalized, use the imperative mood, and should not end in a period.
142
143 The body of a commit message should explain what changes were made and why (but not *how*).
144
145 If a commit addresses a GitHub issue, please include the issue title and number in the
146 body. Summarize the issue if its title is not descriptive enough.