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