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