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 * The second time you contribute to Worg
  81
  82 1. Go to your =Worg/= directory.
  83
  84 2. Be sure to "pull" the last version of the repository.
  85
  86 3. Make some changes.
  87
  88 4. Commit your changes on your local repository:
  89
  90    : ~$ git commit -a -m "summary comment about all changes"
  91
  92 5. Push your change on the remote repository
  93
  94    : ~$ git push
  95
  96 * Getting organized
  97
  98 The Worg TODO file is =worg-todo.org=.  If you are a Worg zealot, maybe you
  99 want to add this file to the list of your agenda files.  For example, here
 100 is my =org-agenda-files= variable:
 101
 102   : (setq org-agenda-files '("~/org/bzg.org" "~/git/Worg/worg-todo.org")
 103
 104 I have an agenda custom command for checking tasks that are assigned to me:
 105
 106   : (org-add-agenda-custom-command '("W" tags "Owner=\"Bastien\""))
 107
 108 The next time someone assigns a task for me, it will appear in my Worg
 109 agenda view.
 110
 111 * Register your changes under your name
 112
 113 Information regarding your name can be stored in your ~/.gitconfig file.
 114
 115 Edit it like this:
 116
 117 : [user]
 118 :        name = FirstName LastName
 119 :        email = you@yourdomain.example.com
 120
 121 Now your changes will be filed under your name.
 122
 123 # I'm not sure this is useful at all:
 124
 125 * Dealing with line endings
 126
 127 Unix, Windows and Mac all have different conventions for marking
 128 the end of a line. This might lead to problems when editing the
 129 same file across platforms. Github advises Linux users to
 130 automatically convert all external files to LF on committing (see
 131 [[http://help.github.com/dealing-with-lineendings]]) by setting:
 132 : $ git config --global core.autocrlf input
 133 For Worg, this is the wrong solution, since there are already
 134 files with both end of line conventions in the repository.
 135 Instead tell git locally not to convert files by setting:
 136 : $ git config core.autocrlf false
 137 Of course you have to be careful not to save Windows files as
 138 Unix files or vice versa, since this would lead to large and
 139 confusing diffs. This should not be a problem with Worg as
 140   - one rarely edits other people's files anyway, and
 141   - Emacs can deal with end of line conventions transparently.
 142
 143 * How Worg publishes itself as HTML?
 144
 145   The server behind http://orgmode.org website takes care of publishing
 146   Worg into =HTML=.  This is done in two steps: the first step is to
 147   pull the Worg directly on the server, the second one is to publish the
 148   last version of Worg on the website.  Both steps are cron'ed every
 149   hour, the first one at 1:00, 2:00, etc. and the second one at 1:30,
 150   2:30.
 151
 152   So for example, if you push a change in Worg at 0:58am, this will be
 153   pulled on the server at 1am and will appear on the website at 1:30am.
 154
 155   Here is the detailed recipe:
 156
 157   1. Configure your =~/.emacs.el= to know about your publishing projects
 158      (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]])
 159
 160   2. Use =(setq org-export-htmlize-output-type 'css)= in ~/.emacs.el
 161
 162      (Do =C-h v org-export-htmlize-output-type= for more information
 163      about this.  Also =C-h v org-export-htmlize-generate-css= might
 164      help.)
 165
 166   3. Create =~/bin/pull-worg.sh= containing this script:
 167
 168      #+BEGIN_SRC sh-mode
 169      #!/bin/bash
 170
 171      # unless this is already done elsewhere:
 172      export PATH=$PATH:/home/you/bin/
 173
 174      # go to the place where you pull Worg
 175      cd /home/you/git/Worg/;
 176
 177      # pull Worg
 178      /home/you/bin/git-pull
 179      #+END_SRC
 180
 181   4. Create =~/bin/pull-worg.sh= containing this script:
 182
 183      #+BEGIN_SRC sh-mode
 184      #!/bin/bash
 185
 186      # Adapt it to point at your emacs executable
 187      /home/you/bin/emacs23 --batch -l ~/.emacs.el -f org-publish-all
 188      #+end_src
 189
 190   5. Cron the two scripts to run every hour, not at the same time
 191
 192      #+BEGIN_SRC generic-mode
 193      0 * * * * /home/you/bin/pull-worg.sh >> /dev/null 2>&1
 194      30 * * * * /home/you/bin/publish-worg.sh >> /dev/null 2>&1
 195      #+END_SRC
 196
 197   6. Sit and do something else while your Org repository is
 198      automagically exported to HTML
 199 * COMMENT Anonymous editing through the "mob" user/branch
 200
 201 If you don't want to register a new account on =repo.or.gz= but still
 202 want to suggest modifications on Worg, you can do this by editing the
 203 "mob" branch of Worg.  For details about the =mob= user, check [[http://repo.or.cz/mob.html][this
 204 webpage]] on repo.or.cz
 205
 206 This branch is usually empty, since interesting changes are quickly
 207 merged into the master branch.  But it is important to make sure that
 208 you pull all changes in any existing =mob= branch before trying to push
 209 yours.
 210
 211 1. Clone the Worg project as the =mob= user:
 212
 213    : ~$ git clone git+ssh://mob@repo.or.cz/srv/git/Worg.git
 214
 215 2. Check out the "mob" branch to avoid conflicts between the =mob=
 216    branch that you will soon create and any existing =mob= branch:
 217
 218    : ~$ git checkout origin/mob
 219
 220    You should get this warning:
 221
 222    : Note: moving to "origin/mob" which isn't a local branch
 223    : If you want to create a new branch from this checkout, you may do so
 224    : now or later) by using -b with the checkout command again. Example:
 225    : git checkout -b <new_branch_name>
 226
 227    Don't worry.
 228
 229 3. Create a new branch named =mob= from this checkout:
 230
 231    : ~$ git checkout -b mob
 232
 233 4. Edit the files, add new files (=git-add=) and commit (=git-commit=)
 234    them as usual.
 235
 236 5. Push the =mob= branch into the Worg remote directory:
 237
 238    : ~$ git push origin mob
 239
 240 You're done!
 241
 242 # FIXME:
 243
 244 # What if two people edit Worg at the same time?
 245 # bzg [2009-07-15 mer]: No problem.  Just try to push and resolve
 246 # conflicts if any.
 247
 248 # Can I have private sections in Worg?
 249 # bzg [2009-07-15 mer]: Sure.  Just add an :AUTHOR: property in
 250 # the property drawer.
 251