1 #+STARTUP: align fold nodlcheck hidestars oddeven lognotestate
2 #+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
3 #+TITLE: How to use git to edit Worg files?
5 #+TAGS: Write(w) Update(u) Fix(f) Check(c)
6 #+EMAIL: mdl AT imapmail DOT org
10 #+OPTIONS: H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
12 [[file:index.org][{Back to Worg's index}]]
16 [[http://git.or.cz][git]] is a fast version control system that lets you collaborate on a project.
17 For details on how to use git, go and read the [[http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html][git tutorial]]. For details on
18 the public git repository, go and read the [[http://repo.or.cz/about.html][about page]] of
21 The homepage of the Worg project is here: http://repo.or.cz/w/Worg.git
22 You can get a read-only clone of the repository with the command:
24 : ~$ git clone http://repo.or.cz/r/Worg.git
26 Since Worg is constantly updated you may want to update your copy
27 of Worg before reading sometimes later. To do so cd into the
28 Worg directory and upgrade your copy of Worg with the command:
30 : ~$ git pull http://repo.or.cz/r/Worg.git
32 If you want to contribute to Worg, keep reading.
34 * The first time you contribute to Worg
36 :CUSTOM_ID: contribute-to-worg
39 1. If you don't have a SSH-key, [[file:worg-git-ssh-key.org][create one]].
41 2. Register a [[http://repo.or.cz/reguser.cgi][new account]] on the git public repository (don't forget to
42 copy paste your public SSH key from =~/.ssh/id_rsa.pub= to the
45 3. *Drop an email to* [[mailto:mdl%20AT%20imapmail%20DOT%20org][Matt Lundin]] mentioning your username on repo.or.cz.
47 4. Install git on your system.
49 5. Clone the project somewhere in a working directory:
51 - If your user name in the shell is the same as the =Login=
52 [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:
54 : ~$ git clone git+ssh://repo.or.cz/srv/git/Worg.git
56 - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:
58 : ~$ git clone git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
60 6. Go to the newly created =Worg/= directory and edit some files.
62 7. If you created files, add them to the git index:
66 8. Commit changes with the appropriate comment:
68 : ~$ git commit -a -m "summary comment about all changes"
70 9. Push your change to Worg:
72 - If your user name in the shell is the same as the
73 =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:
77 - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:
79 : ~$ git remote add public git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
85 If you get a git error message looking like the one at the bottom
86 of this page, then this means that you've forgotten to drop a mail
89 * The second time you contribute to Worg
91 1. Go to your =Worg/= directory.
93 2. Be sure to "pull" the last version of the repository.
95 : ~$ git pull --rebase
97 3. Make some changes. (If you want to learn more about various git
98 workflow, read [[file:worg-git-advanced.org][this page]].)
100 4. Commit your changes on your local repository:
102 : ~$ git commit -a -m "summary comment about all changes"
104 5. Push your change on the remote repository
111 The Worg TODO file is =worg-todo.org=. If you are a Worg zealot, maybe you
112 want to add this file to the list of your agenda files. For example, here
113 is my =org-agenda-files= variable:
115 : (setq org-agenda-files '("~/org/bzg.org" "~/git/Worg/worg-todo.org")
117 I have an agenda custom command for checking tasks that are assigned to me:
119 : (org-add-agenda-custom-command '("W" tags "Owner=\"Bastien\""))
121 The next time someone assigns a task for me, it will appear in my Worg
124 ** Register your changes under your name
126 Information regarding your name can be stored in your global
127 ~/.gitconfig file, or in Worg/.git/config
132 : name = FirstName LastName
133 : email = you@yourdomain.example.com
135 Now your changes will be filed under your name.
137 # I'm not sure this is useful at all:
139 ** Rebase to avoid merging commits
140 It's good practice to pull the current version of the repository
141 before making your own additions. But even if you do, someone might
142 make a change while you are working. So it will often be necessary
143 to pull immediately before pushing your new commit. In this
144 situation, if you use 'git pull' directly, then a 'merge commit'
145 will be generated, looking like this:
148 commit aaaabbbbbbbbbaaaaaaaaabbbbbbbb
149 Merge: bababa efefefef
150 Author: Some one <name@domain>
151 Date: Wed Nov 24 00:00:01 2010 -0700
153 Merge branch 'master' of git+ssh://repo.or.cz/srv/git/Worg
156 That's not a major problem, but it's nice to keep the commit logs
157 free of this stuff. To avoid generating the merge commit, use the
158 =--rebase= option when pulling:
160 : ~$ git pull --rebase
162 Basically this means that your commit will be put to the top of the
163 stack, as if no one had made any additions while you were
164 working. More advanced git users might make their changes in a
165 personal branch, and then rebase that branch against a freshly
166 pulled master branch before merging it in to master. The end result
167 would be the same as pulling with =--rebase=.
169 ** Dealing with line endings
171 Unix, Windows and Mac all have different conventions for marking
172 the end of a line. This might lead to problems when editing the
173 same file across platforms. Github advises Linux users to
174 automatically convert all external files to LF on committing (see
175 [[http://help.github.com/dealing-with-lineendings]]) by setting:
176 : $ git config --global core.autocrlf input
177 For Worg, this is the wrong solution, since there are already
178 files with both end of line conventions in the repository.
179 Instead tell git locally not to convert files by setting:
180 : $ git config core.autocrlf false
181 Of course you have to be careful not to save Windows files as
182 Unix files or vice versa, since this would lead to large and
183 confusing diffs. This should not be a problem with Worg as
184 - one rarely edits other people's files anyway, and
185 - Emacs can deal with end of line conventions transparently.
187 ** Git usage for people who just want to send patches
189 See [[file:worg-git-advanced.org][this page]].
191 * COMMENT Anonymous editing through the "mob" user/branch
193 If you don't want to register a new account on =repo.or.gz= but still
194 want to suggest modifications on Worg, you can do this by editing the
195 "mob" branch of Worg. For details about the =mob= user, check [[http://repo.or.cz/mob.html][this
196 webpage]] on repo.or.cz
198 This branch is usually empty, since interesting changes are quickly
199 merged into the master branch. But it is important to make sure that
200 you pull all changes in any existing =mob= branch before trying to push
203 1. Clone the Worg project as the =mob= user:
205 : ~$ git clone git+ssh://mob@repo.or.cz/srv/git/Worg.git
207 2. Check out the "mob" branch to avoid conflicts between the =mob=
208 branch that you will soon create and any existing =mob= branch:
210 : ~$ git checkout origin/mob
212 You should get this warning:
214 : Note: moving to "origin/mob" which isn't a local branch
215 : If you want to create a new branch from this checkout, you may do so
216 : now or later) by using -b with the checkout command again. Example:
217 : git checkout -b <new_branch_name>
221 3. Create a new branch named =mob= from this checkout:
223 : ~$ git checkout -b mob
225 4. Edit the files, add new files (=git-add=) and commit (=git-commit=)
228 5. Push the =mob= branch into the Worg remote directory:
230 : ~$ git push origin mob
236 # What if two people edit Worg at the same time?
237 # bzg [2009-07-15 mer]: No problem. Just try to push and resolve
240 # Can I have private sections in Worg?
241 # bzg [2009-07-15 mer]: Sure. Just add an :AUTHOR: property in
242 # the property drawer.
244 * Example error message
246 Git error message, when you don't have push permissions to Worg:
249 : Counting objects: 5, done.
250 : Delta compression using up to 2 threads.
251 : Compressing objects: 100% (3/3), done.
252 : Writing objects: 100% (3/3), 463 bytes, done.
253 : Total 3 (delta 2), reused 0 (delta 0)
254 : error: unable to create temporary sha1 filename ./objects/64: File exists
256 : fatal: failed to write object
257 : error: unpack failed: unpacker exited with error code
258 : To git+ssh://myUserName@repo.or.cz/srv/git/Worg.git
259 : ! [remote rejected] master -> master (n/a (unpacker error))
260 : error: failed to push some refs to
261 : 'git+ssh://myUserName@repo.or.cz/srv/git/Worg.git'