Reorganizing the page. Adding a link to worg-git-advanced.

[Worg.git] / worg-git.org

#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+TITLE:      How to use git to edit Worg files?
#+AUTHOR:     Worg people
#+TAGS:       Write(w) Update(u) Fix(f) Check(c)
#+EMAIL:      bzg AT altern DOT org
#+LANGUAGE:   en
#+PRIORITIES: A C B
#+CATEGORY:   worg
#+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

[[file:index.org][{Back to Worg's index}]]

* What is git?

[[http://git.or.cz][git]] is a fast version control system that lets you collaborate on a project.
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
the public git repository, go and read the [[http://repo.or.cz/about.html][about page]] of
http://repo.or.cz/.

The homepage of the Worg project is here: http://repo.or.cz/w/Worg.git
You can get a read-only clone of the repository with the command:

   : ~$ git clone http://repo.or.cz/r/Worg.git

Since Worg is constantly updated you may want to update your copy
of Worg before reading sometimes later.  To do so cd into the
Worg directory and upgrade your copy of Worg with the command:

   : ~$ git pull http://repo.or.cz/r/Worg.git



If you want to contribute to Worg, keep reading.

* The first time you contribute to Worg
  :PROPERTIES:
  :CUSTOM_ID: contribute-to-worg
  :END:


1. If you don't have a SSH-key, [[file:worg-git-ssh-key.org][create one]].

2. Register a [[http://repo.or.cz/reguser.cgi][new account]] on the git public repository (don't forget to
   copy paste your public SSH key from =~/.ssh/id_rsa.pub= to the
   registration form.)

3. *Drop an email to* [[mailto:bzg%20AT%20altern%20DOT%20org][Bastien]] mentioning your username on repo.or.cz.

4. Install git on your system.

5. Clone the project somewhere in a working directory:

   - If your user name in the shell is the same as the =Login=
     [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:

     : ~$ git clone git+ssh://repo.or.cz/srv/git/Worg.git

   - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:

     : ~$ git clone git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git

6. Go to the newly created =Worg/= directory and edit some files.

7. If you created files, add them to the git index:

   : ~$ git add *.org

8. Commit changes with the appropriate comment:

   : ~$ git commit -a -m "summary comment about all changes"

9. Push your change to Worg:

   - If your user name in the shell is the same as the
     =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:

     : ~$ git push

   - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:

     : ~$ git remote add public git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git

     Then do a:

     : ~$ git push public

     If you get a git error message looking like the one at the bottom
     of this page, then this means that you've forgotten to drop a mail
     to Bastien (see step 3).

* The second time you contribute to Worg

1. Go to your =Worg/= directory.

2. Be sure to "pull" the last version of the repository.

3. Make some changes.  (If you want to learn more about various git
   workflow, read [[file:worg-git-advanced.org][this page]].)

4. Commit your changes on your local repository:

   : ~$ git commit -a -m "summary comment about all changes"

5. Push your change on the remote repository

   : ~$ git push

* Going deeper
** Getting organized

The Worg TODO file is =worg-todo.org=.  If you are a Worg zealot, maybe you
want to add this file to the list of your agenda files.  For example, here
is my =org-agenda-files= variable:

  : (setq org-agenda-files '("~/org/bzg.org" "~/git/Worg/worg-todo.org")

I have an agenda custom command for checking tasks that are assigned to me:

  : (org-add-agenda-custom-command '("W" tags "Owner=\"Bastien\""))

The next time someone assigns a task for me, it will appear in my Worg
agenda view.

** Register your changes under your name

Information regarding your name can be stored in your ~/.gitconfig file.

Edit it like this:

: [user]
:        name = FirstName LastName
:        email = you@yourdomain.example.com

Now your changes will be filed under your name.

# I'm not sure this is useful at all:

** Dealing with line endings

Unix, Windows and Mac all have different conventions for marking
the end of a line. This might lead to problems when editing the
same file across platforms. Github advises Linux users to
automatically convert all external files to LF on committing (see
[[http://help.github.com/dealing-with-lineendings]]) by setting:
: $ git config --global core.autocrlf input
For Worg, this is the wrong solution, since there are already
files with both end of line conventions in the repository.
Instead tell git locally not to convert files by setting:
: $ git config core.autocrlf false
Of course you have to be careful not to save Windows files as
Unix files or vice versa, since this would lead to large and
confusing diffs. This should not be a problem with Worg as
  - one rarely edits other people's files anyway, and
  - Emacs can deal with end of line conventions transparently.

** Git usage for people who just want to send patches

See [[file:worg-git-advanced.org][this page]].

* How Worg publishes itself as HTML?

  The server behind http://orgmode.org website takes care of publishing
  Worg into =HTML=.  This is done in two steps: the first step is to
  pull the Worg directly on the server, the second one is to publish the
  last version of Worg on the website.  Both steps are cron'ed every
  hour, the first one at 1:00, 2:00, etc. and the second one at 1:30,
  2:30.

  So for example, if you push a change in Worg at 0:58am, this will be
  pulled on the server at 1am and will appear on the website at 1:30am.

  Here is the detailed recipe:

  1. Configure your =~/.emacs.el= to know about your publishing projects
     (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]])

  2. Use =(setq org-export-htmlize-output-type 'css)= in ~/.emacs.el

     (Do =C-h v org-export-htmlize-output-type= for more information
     about this.  Also =C-h v org-export-htmlize-generate-css= might
     help.)

  3. Create =~/bin/pull-worg.sh= containing this script:

     #+BEGIN_SRC sh-mode
     #!/bin/bash

     # unless this is already done elsewhere:
     export PATH=$PATH:/home/you/bin/

     # go to the place where you pull Worg
     cd /home/you/git/Worg/;

     # pull Worg
     /home/you/bin/git-pull
     #+END_SRC

  4. Create =~/bin/publish-worg.sh= containing this script:

     #+BEGIN_SRC sh-mode
     #!/bin/bash

     # Adapt it to point at your emacs executable
     /home/you/bin/emacs23 --batch -l ~/.emacs.el -f org-publish-all
     #+end_src

  5. Cron the two scripts to run every hour, not at the same time

     #+BEGIN_SRC generic-mode
     0 * * * * /home/you/bin/pull-worg.sh >> /dev/null 2>&1
     30 * * * * /home/you/bin/publish-worg.sh >> /dev/null 2>&1
     #+END_SRC

  6. Sit and do something else while your Org repository is
     automagically exported to HTML
* COMMENT Anonymous editing through the "mob" user/branch

If you don't want to register a new account on =repo.or.gz= but still
want to suggest modifications on Worg, you can do this by editing the
"mob" branch of Worg.  For details about the =mob= user, check [[http://repo.or.cz/mob.html][this
webpage]] on repo.or.cz

This branch is usually empty, since interesting changes are quickly
merged into the master branch.  But it is important to make sure that
you pull all changes in any existing =mob= branch before trying to push
yours.

1. Clone the Worg project as the =mob= user:

   : ~$ git clone git+ssh://mob@repo.or.cz/srv/git/Worg.git

2. Check out the "mob" branch to avoid conflicts between the =mob=
   branch that you will soon create and any existing =mob= branch:

   : ~$ git checkout origin/mob

   You should get this warning:

   : Note: moving to "origin/mob" which isn't a local branch
   : If you want to create a new branch from this checkout, you may do so
   : now or later) by using -b with the checkout command again. Example:
   : git checkout -b <new_branch_name>

   Don't worry.

3. Create a new branch named =mob= from this checkout:

   : ~$ git checkout -b mob

4. Edit the files, add new files (=git-add=) and commit (=git-commit=)
   them as usual.

5. Push the =mob= branch into the Worg remote directory:

   : ~$ git push origin mob

You're done!

# FIXME:

# What if two people edit Worg at the same time?
# bzg [2009-07-15 mer]: No problem.  Just try to push and resolve
# conflicts if any.

# Can I have private sections in Worg?
# bzg [2009-07-15 mer]: Sure.  Just add an :AUTHOR: property in
# the property drawer.

* Example error message

Git error message, when you don't have push permissions to Worg:

       : % git push
       : Counting objects: 5, done.
       : Delta compression using up to 2 threads.
       : Compressing objects: 100% (3/3), done.
       : Writing objects: 100% (3/3), 463 bytes, done.
       : Total 3 (delta 2), reused 0 (delta 0)
       : error: unable to create temporary sha1 filename ./objects/64: File exists
       : 
       : fatal: failed to write object
       : error: unpack failed: unpacker exited with error code
       : To git+ssh://myUserName@repo.or.cz/srv/git/Worg.git
       :  ! [remote rejected] master -> master (n/a (unpacker error))
       : error: failed to push some refs to
       :   'git+ssh://myUserName@repo.or.cz/srv/git/Worg.git'