1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
.. _development-workflow:
====================
Development workflow
====================
You already have your own forked copy of the nitime_ repository, by
following :ref:`forking`, :ref:`set-up-fork`, and you have configured
git_ by following :ref:`configure-git`.
Workflow summary
================
* Keep your ``master`` branch clean of edits that have not been merged
to the main nitime_ development repo. Your ``master`` then will follow
the main nitime_ repository.
* Start a new *feature branch* for each set of edits that you do.
* If you can avoid it, try not to merge other branches into your feature
branch while you are working.
* Ask for review!
This way of working really helps to keep work well organized, and in
keeping history as clear as possible.
See - for example - `linux git workflow`_.
Making a new feature branch
===========================
::
git branch my-new-feature
git checkout my-new-feature
Generally, you will want to keep this also on your public github_ fork
of nitime_. To do this, you `git push`_ this new branch up to your github_
repo. Generally (if you followed the instructions in these pages, and
by default), git will have a link to your github_ repo, called
``origin``. You push up to your own repo on github_ with::
git push origin my-new-feature
From now on git_ will know that ``my-new-feature`` is related to the
``my-new-feature`` branch in the github_ repo.
The editing workflow
====================
Overview
--------
::
# hack hack
git add my_new_file
git commit -am 'NF - some message'
git push
In more detail
--------------
#. Make some changes
#. See which files have changed with ``git status`` (see `git status`_).
You'll see a listing like this one::
# On branch ny-new-feature
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: README
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# INSTALL
no changes added to commit (use "git add" and/or "git commit -a")
#. Check what the actual changes are with ``git diff`` (`git diff`_).
#. Add any new files to version control ``git add new_file_name`` (see
`git add`_).
#. To commit all modified files into the local copy of your repo,, do
``git commit -am 'A commit message'``. Note the ``-am`` options to
``commit``. The ``m`` flag just signals that you're going to type a
message on the command line. The ``a`` flag - you can just take on
faith - or see `why the -a flag?`_. See also the `git commit`_ manual
page.
#. To push the changes up to your forked repo on github_, do a ``git
push`` (see `git push`).
Asking for code review
======================
#. Go to your repo URL - e.g. ``http://github.com/your-user-name/nitime``.
#. Click on the *Branch list* button:
.. image:: branch_list.png
#. Click on the *Compare* button for your feature branch - here ``my-new-feature``:
.. image:: branch_list_compare.png
#. If asked, select the *base* and *comparison* branch names you want to
compare. Usually these will be ``master`` and ``my-new-feature``
(where that is your feature branch name).
#. At this point you should get a nice summary of the changes. Copy the
URL for this, and post it to the `nitime mailing list`_, asking for
review. The URL will look something like:
``http://github.com/your-user-name/nitime/compare/master...my-new-feature``.
There's an example at
http://github.com/matthew-brett/nipy/compare/master...find-install-data
See: http://github.com/blog/612-introducing-github-compare-view for
more detail.
The generated comparison, is between your feature branch
``my-new-feature``, and the place in ``master`` from which you branched
``my-new-feature``. In other words, you can keep updating ``master``
without interfering with the output from the comparison. More detail?
Note the three dots in the URL above (``master...my-new-feature``) and
see :ref:`dot2-dot3`.
Asking for your changes to be merged with the main repo
=======================================================
When you are ready to ask for the merge of your code:
#. Go to the URL of your forked repo, say
``http://github.com/your-user-name/nitime.git``.
#. Click on the 'Pull request' button:
.. image:: pull_button.png
Enter a message; we suggest you select only ``nitime`` as the
recipient. The message will go to the `nitime mailing list`_. Please
feel free to add others from the list as you like.
Merging from trunk
==================
This updates your code from the upstream `nitime github`_ repo.
Overview
--------
::
# go to your master branch
git checkout master
# pull changes from github
git fetch upstream
# merge from upstream
git merge upstream/master
In detail
---------
We suggest that you do this only for your ``master`` branch, and leave
your 'feature' branches unmerged, to keep their history as clean as
possible. This makes code review easier::
git checkout master
Make sure you have done :ref:`linking-to-upstream`.
Merge the upstream code into your current development by first pulling
the upstream repo to a copy on your local machine::
git fetch upstream
then merging into your current branch::
git merge upstream/master
Deleting a branch on github_
============================
::
git checkout master
# delete branch locally
git branch -D my-unwanted-branch
# delete branch on github
git push origin :my-unwanted-branch
(Note the colon ``:`` before ``test-branch``. See also:
http://github.com/guides/remove-a-remote-branch
Several people sharing a single repository
==========================================
If you want to work on some stuff with other people, where you are all
committing into the same repository, or even the same branch, then just
share it via github_.
First fork nitime into your account, as from :ref:`forking`.
Then, go to your forked repository github page, say
``http://github.com/your-user-name/nitime``
Click on the 'Admin' button, and add anyone else to the repo as a
collaborator:
.. image:: pull_button.png
Now all those people can do::
git clone git@githhub.com:your-user-name/nitime.git
Remember that links starting with ``git@`` use the ssh protocol and are
read-write; links starting with ``git://`` are read-only.
Your collaborators can then commit directly into that repo with the
usual::
git commit -am 'ENH - much better code'
git push origin master # pushes directly into your repo
Exploring your repository
=========================
To see a graphical representation of the repository branches and
commits::
gitk --all
To see a linear list of commits for this branch::
git log
You can also look at the `network graph visualizer`_ for your github_
repo.
.. include:: git_links.inc
|
