Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 213 lines (151 sloc) 7.637 kb
74aecfac » willkg
2011-09-06 Adds chapter references for irc, bugzilla and git.
1 .. index:: git, github
2
3 .. _git-chapter:
4
5
1556c33b » davedash
2011-05-10 Dev Process
6 Git and Github
7 ==============
8
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
9 Unless you have a good reason you should be using ``git`` and GitHub_ for
10 version control. One notable exception is many of our projects rely on SVN for
11 localizers. We'll be attempting to phase that out.
1556c33b » davedash
2011-05-10 Dev Process
12
b63771a8 » tofumatt
2011-05-25 Move the Resources header to the top
13 Git Resources
14 -------------
15
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
16 If you don't know ``git`` or haven't used it in a team, fear not! There are lots
17 of awesome sites for git newbies. We recommend:
18
19 * Help.Github_ can help you get started with ``git`` regardless of your
20 operating system. If you haven't used GitHub_ before, it's the perfect crash
21 course. There's also some good info about ``git`` itself. You can ignore the
22 "deploy" section, as we have our own deployment process at Mozilla.
23 * `Pro Git`_ is probably the best ``git`` resource in existence. It covers
24 pretty much everything you'd want to know about ``git``, so it's quite
25 lengthy, but it's a great read to get to know the basics or to use as a
26 reference. `Pro Git`_ is written by one of the developers at GitHub_.
27 * There's a good `list of git resources on StackOverflow`_. It lists tools,
28 tutorials, reference guides, etc. A lot of handy stuff there.
29
30 Next time you start a project, use ``git``/GitHub_! Working on a project by
31 yourself is a bit different than working with others, but start with some basic
32 ``git`` commands (clone, branch, merge) and some of the more wild stuff
33 (multiple origins, rebasing, etc.) will make more sense.
cd16d9a9 » groovecoder
2011-09-25 create a "git practices at mozilla" section
34
35 .. _Help.Github: http://help.github.com/
32e77806 » vtsatskin
2014-05-08 Fix broken Pro Git url
36 .. _`Pro Git`: http://git-scm.com/book/
cd16d9a9 » groovecoder
2011-09-25 create a "git practices at mozilla" section
37 .. _`list of git resources on StackOverflow`: http://stackoverflow.com/questions/315911/git-for-beginners-the-definitive-practical-guide
38
39 Git Practices at Mozilla
40 ------------------------
41
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
42 * Read about the `git-flow model`_. We work similarly to this at Mozilla, except
43 we use ``master`` as our development branch, ``prod`` for our production
44 branch, and ``bug-$BUG_NUMBER`` as our feature branches. Once you get to know
45 ``git``, understanding how to use/manage branches effectively will allow you
46 to keep different bug fixes and features in their own branches. This is
47 **really awesome**, especially if regressions crop up!
1992e4cc » groovecoder
2011-09-19 extra article for git submodules
48 * We use ``git submodule`` for our libraries. This `git submodules explained`_
49 article helps you understand how they work.
cd16d9a9 » groovecoder
2011-09-25 create a "git practices at mozilla" section
50 * We often use ``git rebase`` to combine and fix commits before merging to
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
51 mozilla origin repositories. This helps code reviews and keeps commit history
52 clean. GitHub has `a good rebase article`_.
69544ebd » willkg
2011-09-06 Cleanup pass
53
976d880d » tofumatt
2011-05-25 Add a few git resources and explain what they're for
54 .. _`git-flow model`: http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/
1992e4cc » groovecoder
2011-09-19 extra article for git submodules
55 .. _`git submodules explained`: http://longair.net/blog/2010/06/02/git-submodules-explained/
cd16d9a9 » groovecoder
2011-09-25 create a "git practices at mozilla" section
56 .. _`a good rebase article`: http://help.github.com/rebase/
1556c33b » davedash
2011-05-10 Dev Process
57
b791f118 » davedash
2011-05-12 Git fu
58 github.com/mozilla
59 ------------------
1556c33b » davedash
2011-05-10 Dev Process
60
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
61 New projects for Mozilla websites should start in the `Mozilla account`_.
69544ebd » willkg
2011-09-06 Cleanup pass
62
ad5f78f5 » peterbe
2012-08-21 Updated nicks to contact for github/mozilla admin.
63 Contact ``jsocol``, ``wenzel`` or ``peterbe`` to be added to individual projects
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
64 you want to have your way with. They hang out in **#webdev** on IRC, which is a
65 fine place to ask for access when you start at Mozilla.
1556c33b » davedash
2011-05-10 Dev Process
66
b791f118 » davedash
2011-05-12 Git fu
67 .. _`Mozilla account`: https://github.com/mozilla
976d880d » tofumatt
2011-05-25 Add a few git resources and explain what they're for
68 .. _GitHub: https://github.com/
b791f118 » davedash
2011-05-12 Git fu
69
3e5105d5 » groovecoder
2011-10-06 info about github service hooks
70 Service Hooks
71 ~~~~~~~~~~~~~
72
73 GitHub has some service hooks that are helpful to Mozilla projects.
74
75 * Bugzilla - posts comments on bugzilla when commit messages reference a
76 bug by id, and closes bugs when commit message says 'fix' or 'close'
77 * IRC - announces repository pushes in an irc channel
78
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
79 Contact ``davedash`` or ``wenzel`` to get access parameters for the hooks.
3e5105d5 » groovecoder
2011-10-06 info about github service hooks
80
b791f118 » davedash
2011-05-12 Git fu
81 Working on projects
82 -------------------
83 In order to work on a project:
84
85 * Fork it into your own account (do not develop directly in ``origin``)
86 * Make a branch for your work
87 * Submit a pull request for review
69544ebd » willkg
2011-09-06 Cleanup pass
88 * Merge your commit into ``master`` which should track the
89 ``origin/master``
b791f118 » davedash
2011-05-12 Git fu
90 * ``git push``
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
91 * Place a link to the commit (as it appears in the origin repository) in the
92 relevant bug.
b791f118 » davedash
2011-05-12 Git fu
93
58129b68 » tofumatt
2011-05-25 Fix typos
94 Commit Messages
e520c44b » willkg
2011-09-06 Cosmetic. Tweaks length of header line.
95 ~~~~~~~~~~~~~~~
b791f118 » davedash
2011-05-12 Git fu
96
97 * Follow these guidelines_.
98 * Should begin with a 50 character summary, with details if needed below.
99 * Should contain ``bug 1234`` somewhere in the summary.
100
101 .. _guidelines: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
102
103 Keeping master in sync
104 ~~~~~~~~~~~~~~~~~~~~~~
105
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
106 You will want to keep your local ``master`` branch in sync. Typically you will
107 rebase your branches with your ``master`` and ultimately you will push your
108 ``master`` to ``origin/master``.
b791f118 » davedash
2011-05-12 Git fu
109
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
110 Let's assume you've defined your ``origin`` remote properly in GitHub. E.g. for
111 Zamboni_. ::
b791f118 » davedash
2011-05-12 Git fu
112
113 origin git@github.com:jbalogh/zamboni.git
114
30b37397 » davedash
2011-05-12 Jenkins
115 .. _Zamboni: https://github.com/jbalogh/zamboni
b791f118 » davedash
2011-05-12 Git fu
116
117 You will want your ``.gitconfig`` to have the following::
118
119 [branch "master"]
120 remote = jbalogh
121 merge = master
122 rebase = true
123
0ca0ac96 » davedash
2011-07-29 Fix ref links.
124
b791f118 » davedash
2011-05-12 Git fu
125 Making life easier
126 ------------------
127
128 Git Tools
129 ~~~~~~~~~
69544ebd » willkg
2011-09-06 Cleanup pass
130
59d638e2 » groovecoder
2012-05-16 add fugitive.vim link
131 **shell**
132
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
133 In order to make life easier we maintain a repository_ of ``git-tools``. These
134 are shell scripts or python scripts that commit all kinds of magic.
b791f118 » davedash
2011-05-12 Git fu
135
136 .. _repository: https://github.com/davedash/git-tools
137
138 Here's a sampling:
139
69544ebd » willkg
2011-09-06 Cleanup pass
140 * ``git here`` will tell you the name of your branch, this is an excellent
b791f118 » davedash
2011-05-12 Git fu
141 building block
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
142 * ``git bugbranch $BUGNUM`` will copy your current branch to an appropriately
143 named bug branch. This uses the :ref:`Bugzilla API <bugzilla-api>`.
144 * ``git compare`` with the appropriate ``git.config`` settings will give you a
145 Github_ compare URL for your branch (you'll need to push to Github_ on your
146 own).
147 * ``git url`` with the appropriate ``git.config`` settings gives you the last
148 commit's URL on Github_.
b791f118 » davedash
2011-05-12 Git fu
149
150 Put these in your path and then fork and make your own tools and share.
151
59d638e2 » groovecoder
2012-05-16 add fugitive.vim link
152 **vim**
153
154 fugitive.vim_ may very well be the best Git wrapper of all time.
155
156 .. _fugitive.vim: https://github.com/tpope/vim-fugitive
157
f9f7410d » pmclanahan
2013-08-15 Add hub to git tools.
158 **hub**
159
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
160 hub_ is a git wrapper (or standalone tool) that allows deep integration of
161 github into your command-line git workflow. You can easily clone, fork,
162 pull-request, and checkout pull-requests locally. Read the page and install it
163 now.
f9f7410d » pmclanahan
2013-08-15 Add hub to git tools.
164
165 .. _hub: http://hub.github.com/
166
b791f118 » davedash
2011-05-12 Git fu
167 Oh My Zsh
168 ~~~~~~~~~
169
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
170 `Oh My Zsh <https://github.com/robbyrussell/oh-my-zsh>` is an excellent
171 collection of zshell scripts that can make your `zsh` environment amazing. It
172 includes a collection of plugins, including ones for ``git`` and Github_.
b791f118 » davedash
2011-05-12 Git fu
173
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
174 Some of these overlap with ``git-tools``. Additionally by using Oh My Zsh you
175 can easily display your current branch and it's dirtiness on your prompt.
b791f118 » davedash
2011-05-12 Git fu
176
177 Here is my prompt::
178
179 dash@awesomepants in ~/Projects/bootcamp/the_code/docs
180 (bootcamp) ± on master!
181
69544ebd » willkg
2011-09-06 Cleanup pass
182 Where:
b791f118 » davedash
2011-05-12 Git fu
183
184 * ``bootcamp`` is my active `virtualenv`.
185 * ``±`` signifies that I'm in a ``git`` repository.
186 * ``master`` is the branch I am in.
187 * ``!`` indicates that there are uncommitted things in my branch.
188
189
190 Development Process
191 -------------------
192
78f9173d » davedash
2011-05-12 Fix a ref
193 See :ref:`bug-life`
b791f118 » davedash
2011-05-12 Git fu
194
195 Looking at someone's code
196 ~~~~~~~~~~~~~~~~~~~~~~~~~
69544ebd » willkg
2011-09-06 Cleanup pass
197
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
198 Sometimes you need to run someone else's code locally. If they've given you a
199 pull request, or a commit hash this is what you need to do to see there code::
b791f118 » davedash
2011-05-12 Git fu
200
3d5d1d7f » peterbe
2011-06-17 corrected typo of 'git add remote ...' to 'git remote add ...'
201 git remote add davedash git@github.com:davedash/zamboni.git
b791f118 » davedash
2011-05-12 Git fu
202 git fetch davedash
203 git co davedash/branch
204
205 Note:
206
207 * The above assumes that someone else was me.
6c2edca6 » willkg
2011-09-07 Converts two-space sequences to one at sentence end
208 * The first line defines a "remote". A remote is simply an alias to a
69544ebd » willkg
2011-09-06 Cleanup pass
209 repository.
cec39fd3 » openjck
2013-10-15 Reformat all paragraphs to be 80 characters wide
210 * The second line fetches all my commit hashes that you don't already have.
211 Usually this is just branches, and commits, but in theory it can be anything.
212 * In the third line I can check out your branch. If you just gave me a commit
213 hash I would do ``git co $COMMIT_HASH``.
Something went wrong with that request. Please try again.