1 WARNING: I am just learning git, so the following could have mistakes.
2 For now, I am making backups of the repository regularly
3 in case anyone, including myself, screws it up. Jon
5 NOTE: To get the files you need to be working on a machine that has a
6 current version of git installed. To build wrf you need to have the
7 requisite libraries installed and environment set up.
8 See the user guide linked from http://openwfm.org/software.html
9 for further information.
11 ***************************************
13 ***************************************
15 First you clone to create a local repository. The first time you create
16 your own branch as a copy of master. If you already have a
17 branch in the archive you create a local branch as a copy of that.
18 To get new files pull from master in the archive. You work all the time in your
19 local branch. Then push your branch to the archive.
21 ***************************************
23 ***************************************
26 1. make sure you are in your branch by git branch before you modify anything
27 2. merge between repositories is by pull only, never by push
28 3. before and after git pull or merge use git log to make sure where you are
29 4. the first line from git log identifies the state of all files uniquely
30 5. before pull you must commit all changes (=to your local repository)
31 6. accumulated changes cause edit conflicts - merge with master often!!
33 Developers with write access:
34 7. only after you push your committed changes will be visible to others
35 8. your changes will get merged into master only when you ask Jon to do that
38 ***************************************
39 *Initial command list (see explanations below)*
40 ***************************************
42 1. Initial setup (substitute your information)
44 git config --global user.name "FirstName LastName"
45 git config --global user.email "user@example.com"
47 (You need to do this only once)
49 2. Local repository setup
51 a) Local developers with write access: make sure ssh math.ucdenver.edu works
52 and you are in group mandel there. Then:
54 git clone ssh://math.cudenver.edu/home/grads/jbeezley/wrf-fire.git
56 b) Everyone else, read access only:
58 git clone git://github.com/jbeezley/wrf-fire.git
60 In either case, this will create a directory wrf-fire with the files. The cloned
61 repository will be created in a hidden directory wrf-fire/.git
63 3. Create your branch:
64 (Substitute <branch> with what you want to name your branch.)
65 (If you have write access, please use branch names of the form <xy>/<branchname>,
66 where xy are your initials, so as not to clutter the repository.)
72 4. Updating <branch> from the shared repository, similar to "cvs update":
74 git pull origin master:master
75 git branch (to make sure you are on your own branch)
76 git checkout <branch> (if necessary)
79 5. Commit your changes:
80 git add <filename> (to add any new files)
81 git commit -a (do not forget the flag -a)
83 6. If you have write acces, copy your changes from the local repository
84 to the share repository:
86 git push origin <branch>:<branch>
88 (The first time, next time you can try the short form, just git push)
90 7. To share your changes:
92 a) If you have write access: ask Jon to merge your branch into master
93 and tell him which commit exactly (first line from git log)
95 b) If you have read-only access: email Jon for instructions how to
96 create and email a patch file with your changes
98 ***********************************
99 *Explanation of the commands above*
100 *and additional useful information*
101 ***********************************
105 git requires that each user be identified with a name and email.
108 2. Local repository setup
110 Only changes committed in the main repository by git push can be seen
111 by others. git commit works with your local repository. This
112 allows you work offline and prevents your changes from being seen by
113 others until you are ready.
119 This will create your branch starting from the commit where you currently are
120 (the latest commit on the master branch by default).
122 git checkout <branch>
124 This will make sure you are on your own branch.
129 Our shared repository contains several branches, by default you will
130 checkout the "master" branch. This is meant to be the stable branch,
131 and only Jon may git push to it. Branches with "origin" are in the
134 To get a list of local branches and see what branch you are on
138 To see remote branches available
142 or to see all branches
146 Among others, you should see 'origin/jbeezley'. To use this branch
147 you need to create your private clone in your local repository by
149 git checkout -b jbeezley origin/jbeezley
151 This will create a local branch, jbeezley, that will automatically be
152 updated by the remote branch, jbeezley, on the shared repository.
153 "origin" is the default name of the shared repository.
155 The first command creates a local branch starting from "master". The
156 second command commits (pushes) this branch to the shared repository.
158 To update your local copy of the jbeezley branch, you can do
160 git checkout jbeezley
161 git pull (git will know you want to pull from origin/jbeezley)
163 and you are on the jbeezley branch at this point. Or, you can
165 git pull origin jbeezley:jbeezley
167 (Of course you can do all that with any other branch, not just jbeezley.)
169 To switch to a different local branch
171 git checkout <branch>
173 4. Updating the repository
175 To synchronize the local repository with the shared one do
179 This will not change your files, only the local repository.
180 Note that git pull is equivalent to git fetch; git merge
182 To get rid of all local changes (like cvs update -C)
186 5. Committing changes
188 If you create any new files, you must tell git about it
192 All new files in the directory tree can be added with
196 (see also 'git rm' and 'git mv') Finally, the changes can be
201 You have to be somewhere in the wrf directory, but it does no matter
202 where, the wrf directory and subdirectories are always committed.
204 This will only commit to your local repository. To add your commits to
205 *your branch* in the shared repository
207 git push origin <branch>:<branch>
209 Ask Jon to add your commits to the master branch.
213 git push origin <local branch>:<destination branch>
215 Because this will modify the shared repository, only use a destination
216 branch which you control. There is a way to automate this so that the
217 branches don't have to be specified (the --track flag may actually take
218 care of this), but I'm not sure how this works. For now, I suggest
219 specifying the branches to be safe.
221 6. Deleting a remote branch
223 A remote branch can be deleted by pushing "nothing" to the branch. For
224 example, if you want to delete the remote branch "oldbranch" on origin,
227 git push origin :oldbranch
229 7. Reverting local changes
231 If you make a change to some files, and you wish to revert those files to
232 a state as in the repository, you can do this with git checkout. To revert
233 all files and restore the state to the last commit:
237 To revert only a single file (<filename>) and to keep all other changes intact:
239 git checkout-index -f <filename>
241 Remember, git by default won't let you do anything that will lose any
242 changes that you've made. Generally, git commands support a '-f' flag that
243 will allow it over-write any changes that you have made; however, once you
244 do this, you will not be able to get the changes back. If you really don't
245 want to lose these changes, then you can just create a temporary local
246 branch to keep them in.
248 git branch <tempbranch>
249 git checkout <tempbranch>
252 This way you can get back to the original branch with the usual git checkout
253 command, and you won't lose the changes. If, later, you wish to put these
254 changes into your main branch (<mainbranch>):
256 git checkout <mainbranch>
257 git merge <tempbranch>
259 You can delete the temporary branch at any time with:
261 git branch -d <tempbranch>
265 For a log of everything you have done in your repository, see the command
267 You can undo changes with reset. The cvs style commands status, log, and
268 diff also work in git.
270 9. diff with other branch:
272 git fetch (to make sure you have current repository)
273 git diff <branch> (for example git diff origin/jb/fire_da)
277 man git : Overview of git commands
278 man git-commit : man page for "git commit" (replace commit with other commands as well)
280 Much of this document was based on the web page:
282 http://wiki.sourcemage.org/Git_Guide
286 http://git.or.cz/course/svn.html
288 There is also a simplified interface to git known as cogito, it is similar to cvs,
289 but I haven't looked at it.
291 http://git.or.cz/course/cvs.html
293 Documentation of common commands
295 http://www.kernel.org/pub/software/scm/git/docs/everyday.html
299 http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
301 11. Magic sequences for specific tasks
303 Magic sequence to see files from somebody else's branch
306 git branch -r (to see the list of branches, then pick the <other_branch> name)
308 if the <other_branch> is not there then (first time only)
309 git checkout --track -b <other_branch> origin/<other_branch>
311 git checkout <other_branch>
313 [now look at the files]
314 git checkout <your_own_branch>
315 git branch (look for * to make sure you are on your own branch)
317 Note: it may be better to set up a separate clone (see the top) for that.
318 Each clone has its own local repository.
320 Magic sequence to get all updates from master brach from the remote
321 repository and merge them into your branch:
323 git checkout <branch>
324 git pull origin master:master
326 git push origin <branch>:<branch>