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:      bzg AT altern 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 If you want to contribute to Worg, keep reading.
  27
  28 * The first time you contribute to Worg
  29   :PROPERTIES:
  30   :CUSTOM_ID: contribute-to-worg
  31   :END:
  32
  33
  34 1. If you don't have a SSH-key, [[file:worg-git-ssh-key.org][create one]].
  35
  36 2. Register a [[http://repo.or.cz/reguser.cgi][new account]] on the git public repository (don't forget to
  37    copy paste your public SSH key from =~/.ssh/id_rsa.pub= to the
  38    registration form.)
  39
  40 3. *Drop an email to* [[mailto:bzg%20AT%20altern%20DOT%20org][Bastien]] mentioning your username on repo.or.cz.
  41
  42 4. Install git on your system.
  43
  44 5. Clone the project somewhere in a working directory:
  45
  46    - If your user name in the shell is the same as the
  47      =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:
  48
  49      : ~$ git clone git+ssh://repo.or.cz/srv/git/Worg.git
  50
  51    - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:
  52
  53      : ~$ git clone git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
  54
  55 6. Go to the newly created =Worg/= directory and edit some files.
  56
  57 7. If you created files, add them to the git index:
  58
  59    : ~$ git add *.org
  60
  61 8. Commit changes with the appropriate comment:
  62
  63    : ~$ git commit -a -m "summary comment about all changes"
  64
  65 9. Push your change to Worg:
  66
  67    - If your user name in the shell is the same as the
  68      =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:
  69
  70      : ~$ git push
  71
  72    - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:
  73
  74      : ~$ git remote add public git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
  75
  76      Then do a:
  77
  78      : ~$ git push public
  79
  80      If you get a git error message looking like [fn:1], then this means that
  81      you've forgotten to drop a mail to Bastien (see step 3).
  82
  83 * The second time you contribute to Worg
  84
  85 1. Go to your =Worg/= directory.
  86
  87 2. Be sure to "pull" the last version of the repository.
  88
  89 3. Make some changes.
  90
  91 4. Commit your changes on your local repository:
  92
  93    : ~$ git commit -a -m "summary comment about all changes"
  94
  95 5. Push your change on the remote repository
  96
  97    : ~$ git push
  98
  99 * Getting organized
 100
 101 The Worg TODO file is =worg-todo.org=.  If you are a Worg zealot, maybe you
 102 want to add this file to the list of your agenda files.  For example, here
 103 is my =org-agenda-files= variable:
 104
 105   : (setq org-agenda-files '("~/org/bzg.org" "~/git/Worg/worg-todo.org")
 106
 107 I have an agenda custom command for checking tasks that are assigned to me:
 108
 109   : (org-add-agenda-custom-command '("W" tags "Owner=\"Bastien\""))
 110
 111 The next time someone assigns a task for me, it will appear in my Worg
 112 agenda view.
 113
 114 * Register your changes under your name
 115
 116 Information regarding your name can be stored in your ~/.gitconfig file.
 117
 118 Edit it like this:
 119
 120 : [user]
 121 :        name = FirstName LastName
 122 :        email = you@yourdomain.example.com
 123
 124 Now your changes will be filed under your name.
 125
 126 # I'm not sure this is useful at all:
 127
 128 * Dealing with line endings
 129
 130 Unix, Windows and Mac all have different conventions for marking
 131 the end of a line. This might lead to problems when editing the
 132 same file across platforms. Github advises Linux users to
 133 automatically convert all external files to LF on committing (see
 134 [[http://help.github.com/dealing-with-lineendings]]) by setting:
 135 : $ git config --global core.autocrlf input
 136 For Worg, this is the wrong solution, since there are already
 137 files with both end of line conventions in the repository.
 138 Instead tell git locally not to convert files by setting:
 139 : $ git config core.autocrlf false
 140 Of course you have to be careful not to save Windows files as
 141 Unix files or vice versa, since this would lead to large and
 142 confusing diffs. This should not be a problem with Worg as
 143   - one rarely edits other people's files anyway, and
 144   - Emacs can deal with end of line conventions transparently.
 145
 146 * How Worg publishes itself as HTML?
 147
 148   The server behind http://orgmode.org website takes care of publishing
 149   Worg into =HTML=.  This is done in two steps: the first step is to
 150   pull the Worg directly on the server, the second one is to publish the
 151   last version of Worg on the website.  Both steps are cron'ed every
 152   hour, the first one at 1:00, 2:00, etc. and the second one at 1:30,
 153   2:30.
 154
 155   So for example, if you push a change in Worg at 0:58am, this will be
 156   pulled on the server at 1am and will appear on the website at 1:30am.
 157
 158   Here is the detailed recipe:
 159
 160   1. Configure your =~/.emacs.el= to know about your publishing projects
 161      (more information on publishing [[http://www.gnu.org/software/emacs/manual/html_node/org/Publishing.html][here]] and [[file:org-tutorials/org-publish-html-tutorial.org][here]])
 162
 163   2. Use =(setq org-export-htmlize-output-type 'css)= in ~/.emacs.el
 164
 165      (Do =C-h v org-export-htmlize-output-type= for more information
 166      about this.  Also =C-h v org-export-htmlize-generate-css= might
 167      help.)
 168
 169   3. Create =~/bin/pull-worg.sh= containing this script:
 170
 171      #+BEGIN_SRC sh-mode
 172      #!/bin/bash
 173
 174      # unless this is already done elsewhere:
 175      export PATH=$PATH:/home/you/bin/
 176
 177      # go to the place where you pull Worg
 178      cd /home/you/git/Worg/;
 179
 180      # pull Worg
 181      /home/you/bin/git-pull
 182      #+END_SRC
 183
 184   4. Create =~/bin/pull-worg.sh= containing this script:
 185
 186      #+BEGIN_SRC sh-mode
 187      #!/bin/bash
 188
 189      # Adapt it to point at your emacs executable
 190      /home/you/bin/emacs23 --batch -l ~/.emacs.el -f org-publish-all
 191      #+end_src
 192
 193   5. Cron the two scripts to run every hour, not at the same time
 194
 195      #+BEGIN_SRC generic-mode
 196      0 * * * * /home/you/bin/pull-worg.sh >> /dev/null 2>&1
 197      30 * * * * /home/you/bin/publish-worg.sh >> /dev/null 2>&1
 198      #+END_SRC
 199
 200   6. Sit and do something else while your Org repository is
 201      automagically exported to HTML
 202 * COMMENT Anonymous editing through the "mob" user/branch
 203
 204 If you don't want to register a new account on =repo.or.gz= but still
 205 want to suggest modifications on Worg, you can do this by editing the
 206 "mob" branch of Worg.  For details about the =mob= user, check [[http://repo.or.cz/mob.html][this
 207 webpage]] on repo.or.cz
 208
 209 This branch is usually empty, since interesting changes are quickly
 210 merged into the master branch.  But it is important to make sure that
 211 you pull all changes in any existing =mob= branch before trying to push
 212 yours.
 213
 214 1. Clone the Worg project as the =mob= user:
 215
 216    : ~$ git clone git+ssh://mob@repo.or.cz/srv/git/Worg.git
 217
 218 2. Check out the "mob" branch to avoid conflicts between the =mob=
 219    branch that you will soon create and any existing =mob= branch:
 220
 221    : ~$ git checkout origin/mob
 222
 223    You should get this warning:
 224
 225    : Note: moving to "origin/mob" which isn't a local branch
 226    : If you want to create a new branch from this checkout, you may do so
 227    : now or later) by using -b with the checkout command again. Example:
 228    : git checkout -b <new_branch_name>
 229
 230    Don't worry.
 231
 232 3. Create a new branch named =mob= from this checkout:
 233
 234    : ~$ git checkout -b mob
 235
 236 4. Edit the files, add new files (=git-add=) and commit (=git-commit=)
 237    them as usual.
 238
 239 5. Push the =mob= branch into the Worg remote directory:
 240
 241    : ~$ git push origin mob
 242
 243 You're done!
 244
 245 # FIXME:
 246
 247 # What if two people edit Worg at the same time?
 248 # bzg [2009-07-15 mer]: No problem.  Just try to push and resolve
 249 # conflicts if any.
 250
 251 # Can I have private sections in Worg?
 252 # bzg [2009-07-15 mer]: Sure.  Just add an :AUTHOR: property in
 253 # the property drawer.
 254
 255
 256 * Footnotes
 257
 258 [fn:1] Git error message, when you don't have push permissions to Worg.
 259        : % git push
 260        : Counting objects: 5, done.
 261        : Delta compression using up to 2 threads.
 262        : Compressing objects: 100% (3/3), done.
 263        : Writing objects: 100% (3/3), 463 bytes, done.
 264        : Total 3 (delta 2), reused 0 (delta 0)
 265        : error: unable to create temporary sha1 filename ./objects/64: File exists
 266        :
 267        : fatal: failed to write object
 268        : error: unpack failed: unpacker exited with error code
 269        : To git+ssh://myUserName@repo.or.cz/srv/git/Worg.git
 270        :  ! [remote rejected] master -> master (n/a (unpacker error))
 271        : error: failed to push some refs to
 272        :   'git+ssh://myUserName@repo.or.cz/srv/git/Worg.git'
 273