worg-git.org

   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?
   4 #+AUTHOR:     Worg people
   5 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   6 #+EMAIL:      mdl AT imapmail DOT org
   7 #+LANGUAGE:   en
   8 #+PRIORITIES: A C B
   9 #+CATEGORY:   worg
  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
  11
  12 [[file:index.org][{Back to Worg's index}]]
  13
  14 * What is git?
  15
  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
  19 http://repo.or.cz/.
  20
  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:
  23
  24    : ~$ git clone http://repo.or.cz/r/Worg.git
  25
  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:
  29
  30    : ~$ git pull http://repo.or.cz/r/Worg.git
  31
  32
  33
  34 If you want to contribute to Worg, keep reading.
  35
  36 * The first time you contribute to Worg
  37   :PROPERTIES:
  38   :CUSTOM_ID: contribute-to-worg
  39   :END:
  40
  41
  42 1. If you don't have a SSH-key, [[file:worg-git-ssh-key.org][create one]].
  43
  44 2. Register a [[http://repo.or.cz/reguser.cgi][new account]] on the git public repository (don't forget to
  45    copy paste your public SSH key from =~/.ssh/id_rsa.pub= to the
  46    registration form.)
  47
  48 3. *Drop an email to* [[mailto:mdl%20AT%20imapmail%20DOT%20org][Matt Lundin]] mentioning your username on repo.or.cz.
  49
  50 4. Install git on your system.
  51
  52 5. Clone the project somewhere in a working directory:
  53
  54    - If your user name in the shell is the same as the =Login=
  55      [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:
  56
  57      : ~$ git clone git+ssh://repo.or.cz/srv/git/Worg.git
  58
  59    - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:
  60
  61      : ~$ git clone git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
  62
  63 6. Go to the newly created =Worg/= directory and edit some files.
  64
  65 7. If you created files, add them to the git index:
  66
  67    : ~$ git add *.org
  68
  69 8. Commit changes with the appropriate comment:
  70
  71    : ~$ git commit -a -m "summary comment about all changes"
  72
  73 9. Push your change to Worg:
  74
  75    - If your user name in the shell is the same as the
  76      =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:
  77
  78      : ~$ git push
  79
  80    - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:
  81
  82      : ~$ git remote add public git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
  83
  84      Then do a:
  85
  86      : ~$ git push public
  87
  88      If you get a git error message looking like the one at the bottom
  89      of this page, then this means that you've forgotten to drop a mail
  90      to Bastien (see step 3).
  91
  92 * The second time you contribute to Worg
  93
  94 1. Go to your =Worg/= directory.
  95
  96 2. Be sure to "pull" the last version of the repository.
  97
  98   : ~$ git pull --rebase
  99
 100 3. Make some changes.  (If you want to learn more about various git
 101    workflow, read [[file:worg-git-advanced.org][this page]].)
 102
 103 4. Commit your changes on your local repository:
 104
 105    : ~$ git commit -a -m "summary comment about all changes"
 106
 107 5. Push your change on the remote repository
 108
 109    : ~$ git push
 110
 111 * Going deeper
 112 ** Getting organized
 113
 114 The Worg TODO file is =worg-todo.org=.  If you are a Worg zealot, maybe you
 115 want to add this file to the list of your agenda files.  For example, here
 116 is my =org-agenda-files= variable:
 117
 118   : (setq org-agenda-files '("~/org/bzg.org" "~/git/Worg/worg-todo.org")
 119
 120 I have an agenda custom command for checking tasks that are assigned to me:
 121
 122   : (org-add-agenda-custom-command '("W" tags "Owner=\"Bastien\""))
 123
 124 The next time someone assigns a task for me, it will appear in my Worg
 125 agenda view.
 126
 127 ** Register your changes under your name
 128
 129 Information regarding your name can be stored in your global
 130 ~/.gitconfig file, or in Worg/.git/config
 131
 132 Edit it like this:
 133
 134 : [user]
 135 :        name = FirstName LastName
 136 :        email = you@yourdomain.example.com
 137
 138 Now your changes will be filed under your name.
 139
 140 # I'm not sure this is useful at all:
 141
 142 ** Rebase to avoid merging commits
 143    It's good practice to pull the current version of the repository
 144    before making your own additions. But even if you do, someone might
 145    make a change while you are working. So it will often be necessary
 146    to pull immediately before pushing your new commit. In this
 147    situation, if you use 'git pull' directly, then a 'merge commit'
 148    will be generated, looking like this:
 149
 150 #+begin_example
 151 commit aaaabbbbbbbbbaaaaaaaaabbbbbbbb
 152 Merge: bababa efefefef
 153 Author: Some one <name@domain>
 154 Date:   Wed Nov 24 00:00:01 2010 -0700
 155
 156     Merge branch 'master' of git+ssh://repo.or.cz/srv/git/Worg
 157 #+end_example
 158
 159    That's not a major problem, but it's nice to keep the commit logs
 160    free of this stuff. To avoid generating the merge commit, use the
 161    =--rebase= option when pulling:
 162
 163   : ~$ git pull --rebase
 164
 165    Basically this means that your commit will be put to the top of the
 166    stack, as if no one had made any additions while you were
 167    working. More advanced git users might make their changes in a
 168    personal branch, and then rebase that branch against a freshly
 169    pulled master branch before merging it in to master. The end result
 170    would be the same as pulling with =--rebase=.
 171
 172 ** Dealing with line endings
 173
 174 Unix, Windows and Mac all have different conventions for marking
 175 the end of a line. This might lead to problems when editing the
 176 same file across platforms. Github advises Linux users to
 177 automatically convert all external files to LF on committing (see
 178 [[http://help.github.com/dealing-with-lineendings]]) by setting:
 179 : $ git config --global core.autocrlf input
 180 For Worg, this is the wrong solution, since there are already
 181 files with both end of line conventions in the repository.
 182 Instead tell git locally not to convert files by setting:
 183 : $ git config core.autocrlf false
 184 Of course you have to be careful not to save Windows files as
 185 Unix files or vice versa, since this would lead to large and
 186 confusing diffs. This should not be a problem with Worg as
 187   - one rarely edits other people's files anyway, and
 188   - Emacs can deal with end of line conventions transparently.
 189
 190 ** Git usage for people who just want to send patches
 191
 192 See [[file:worg-git-advanced.org][this page]].
 193
 194 * COMMENT Anonymous editing through the "mob" user/branch
 195
 196 If you don't want to register a new account on =repo.or.gz= but still
 197 want to suggest modifications on Worg, you can do this by editing the
 198 "mob" branch of Worg.  For details about the =mob= user, check [[http://repo.or.cz/mob.html][this
 199 webpage]] on repo.or.cz
 200
 201 This branch is usually empty, since interesting changes are quickly
 202 merged into the master branch.  But it is important to make sure that
 203 you pull all changes in any existing =mob= branch before trying to push
 204 yours.
 205
 206 1. Clone the Worg project as the =mob= user:
 207
 208    : ~$ git clone git+ssh://mob@repo.or.cz/srv/git/Worg.git
 209
 210 2. Check out the "mob" branch to avoid conflicts between the =mob=
 211    branch that you will soon create and any existing =mob= branch:
 212
 213    : ~$ git checkout origin/mob
 214
 215    You should get this warning:
 216
 217    : Note: moving to "origin/mob" which isn't a local branch
 218    : If you want to create a new branch from this checkout, you may do so
 219    : now or later) by using -b with the checkout command again. Example:
 220    : git checkout -b <new_branch_name>
 221
 222    Don't worry.
 223
 224 3. Create a new branch named =mob= from this checkout:
 225
 226    : ~$ git checkout -b mob
 227
 228 4. Edit the files, add new files (=git-add=) and commit (=git-commit=)
 229    them as usual.
 230
 231 5. Push the =mob= branch into the Worg remote directory:
 232
 233    : ~$ git push origin mob
 234
 235 You're done!
 236
 237 # FIXME:
 238
 239 # What if two people edit Worg at the same time?
 240 # bzg [2009-07-15 mer]: No problem.  Just try to push and resolve
 241 # conflicts if any.
 242
 243 # Can I have private sections in Worg?
 244 # bzg [2009-07-15 mer]: Sure.  Just add an :AUTHOR: property in
 245 # the property drawer.
 246
 247 * Example error message
 248
 249 Git error message, when you don't have push permissions to Worg:
 250
 251        : % git push
 252        : Counting objects: 5, done.
 253        : Delta compression using up to 2 threads.
 254        : Compressing objects: 100% (3/3), done.
 255        : Writing objects: 100% (3/3), 463 bytes, done.
 256        : Total 3 (delta 2), reused 0 (delta 0)
 257        : error: unable to create temporary sha1 filename ./objects/64: File exists
 258        :
 259        : fatal: failed to write object
 260        : error: unpack failed: unpacker exited with error code
 261        : To git+ssh://myUserName@repo.or.cz/srv/git/Worg.git
 262        :  ! [remote rejected] master -> master (n/a (unpacker error))
 263        : error: failed to push some refs to
 264        :   'git+ssh://myUserName@repo.or.cz/srv/git/Worg.git'
 265