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
  23 * The first time you contribute to Worg
  24   :PROPERTIES:
  25   :CUSTOM_ID: contribute-to-worg
  26   :END:
  27
  28
  29 1. If you don't have a SSH-key, [[file:worg-git-ssh-key.org][create one]].
  30
  31 2. Register a [[http://repo.or.cz/m/reguser.cgi][new account]] on the git public repository.
  32
  33 3. Drop an email to [[mailto:bzg%20AT%20altern%20DOT%20org][Bastien]] mentioning your username on repo.or.cz
  34
  35 4. Install git on your system.
  36
  37 5. Clone the project somewhere in a working directory:
  38
  39    : ~$ git clone git+ssh://repo.or.cz/srv/git/Worg.git
  40
  41 6. Go to the newly created =Worg/= directory and edit some files.
  42
  43 7. If you created files, add them to the git index:
  44
  45    : ~$ git add *.org
  46
  47 8. Commit changes with the appropriate ChangeLog:
  48
  49   : ~$ git commit -a -m "My changelog"
  50
  51 9. Push your change to Worg:
  52
  53   : ~$ git push
  54
  55   This stage didn't work for me, instead I had to add a remote like
  56   so:
  57
  58   : ~$ git remote add public git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
  59
  60   Where <UserName> is the username you supplied repo.or.cz.  Then do
  61   a:
  62
  63   : ~$ git push public
  64
  65 * The second time you contribute to Worg
  66
  67 1. Go to your =Worg/= directory.
  68
  69 2. Be sure to "pull" the last version of the repository.
  70
  71 3. Make some changes.
  72
  73 4. Commit your changes on your local repository:
  74
  75    : ~$ git commit -a -m "My ChangeLog"
  76
  77 5. Push your change on the remote repository
  78
  79    : ~$ git push
  80
  81 * Getting organized
  82
  83 The Worg TODO file is =worg-todo.org=.  If you are a Worg zealot, maybe you
  84 want to add this file to the list of your agenda files.  For example, here
  85 is my =org-agenda-files= variable:
  86
  87   : (setq org-agenda-files '("~/org/bzg.org" "~/git/Worg/worg-todo.org")
  88
  89 I have an agenda custom command for checking tasks that are assigned to me:
  90
  91   : (org-add-agenda-custom-command '("W" tags "Owner=\"Bastien\""))
  92
  93 The next time someone assigns a task for me, it will appear in my Worg
  94 agenda view.
  95
  96 * Register your changes under your name
  97
  98 Information regarding your name can be stored in your ~/.gitconfig file.
  99
 100 Edit it like this:
 101
 102 : [user]
 103 :        name = Your Name Goes Here
 104 :        email = you@yourdomain.example.com
 105
 106 Now your changes will be filed under your name.
 107
 108 # I'm not sure this is useful at all:
 109
 110 * How Worg publishes itself as HTML?
 111
 112   The server behind http://orgmode.org website takes care of publishing
 113   Worg into =HTML=.  This is done in two steps: the first step is to
 114   pull the Worg directly on the server, the second one is to publish the
 115   last version of Worg on the website.  Both steps are cron'ed every
 116   hour, the first one at 1:00, 2:00, etc. and the second one at 1:30,
 117   2:30.
 118
 119   So for example, if you push a change in Worg at 0:58am, this will be
 120   pulled on the server at 1am and will appear on the website at 1:30am.
 121
 122   Here is the detailed recipe:
 123
 124   1. Configure your =~/.emacs.el= to know about your publishing projects
 125      (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]])
 126
 127   2. Use =(setq org-export-htmlize-output-type 'css)= in ~/.emacs.el
 128
 129      (Do =C-h v org-export-htmlize-output-type= for more information
 130      about this.  Also =C-h v org-export-htmlize-generate-css= might
 131      help.)
 132
 133   3. Create =~/bin/pull-worg.sh= containing this script:
 134
 135      #+BEGIN_SRC sh-mode
 136      #!/bin/bash
 137
 138      # unless this is already done elsewhere:
 139      export PATH=$PATH:/home/you/bin/
 140
 141      # go to the place where you pull Worg
 142      cd /home/you/git/Worg/;
 143
 144      # pull Worg
 145      /home/you/bin/git-pull
 146      #+END_SRC
 147
 148   4. Create =~/bin/pull-worg.sh= containing this script:
 149
 150      #+BEGIN_SRC sh-mode
 151      #!/bin/bash
 152
 153      # Adapt it to point at your emacs executable
 154      /home/you/bin/emacs23 --batch -l ~/.emacs.el -f org-publish-all
 155      #+end_src
 156
 157   5. Cron the two scripts to run every hour, not at the same time
 158
 159      #+BEGIN_SRC generic-mode
 160      0 * * * * /home/you/bin/pull-worg.sh >> /dev/null 2>&1
 161      30 * * * * /home/you/bin/publish-worg.sh >> /dev/null 2>&1
 162      #+END_SRC
 163
 164   6. Sit and do something else while your Org repository is
 165      automagically exported to HTML
 166 * COMMENT Anonymous editing through the "mob" user/branch
 167
 168 If you don't want to register a new account on =repo.or.gz= but still
 169 want to suggest modifications on Worg, you can do this by editing the
 170 "mob" branch of Worg.  For details about the =mob= user, check [[http://repo.or.cz/mob.html][this
 171 webpage]] on repo.or.cz
 172
 173 This branch is usually empty, since interesting changes are quickly
 174 merged into the master branch.  But it is important to make sure that
 175 you pull all changes in any existing =mob= branch before trying to push
 176 yours.
 177
 178 1. Clone the Worg project as the =mob= user:
 179
 180    : ~$ git clone git+ssh://mob@repo.or.cz/srv/git/Worg.git
 181
 182 2. Check out the "mob" branch to avoid conflicts between the =mob=
 183    branch that you will soon create and any existing =mob= branch:
 184
 185    : ~$ git checkout origin/mob
 186
 187    You should get this warning:
 188
 189    : Note: moving to "origin/mob" which isn't a local branch
 190    : If you want to create a new branch from this checkout, you may do so
 191    : now or later) by using -b with the checkout command again. Example:
 192    : git checkout -b <new_branch_name>
 193
 194    Don't worry.
 195
 196 3. Create a new branch named =mob= from this checkout:
 197
 198    : ~$ git checkout -b mob
 199
 200 4. Edit the files, add new files (=git-add=) and commit (=git-commit=)
 201    them as usual.
 202
 203 5. Push the =mob= branch into the Worg remote directory:
 204
 205    : ~$ git push origin mob
 206
 207 You're done!
 208
 209 # FIXME:
 210
 211 # What if two people edit Worg at the same time?
 212 # bzg [2009-07-15 mer]: No problem.  Just try to push and resolve
 213 # conflicts if any.
 214
 215 # Can I have private sections in Worg?
 216 # bzg [2009-07-15 mer]: Sure.  Just add an :AUTHOR: property in
 217 # the property drawer.
 218