Support via Liberapay, GitHub or PayPal

About Worg

Table of Contents


What is Worg? What is its relation to Org?

Org is an Emacs mode for keeping notes, maintaining to-do lists, and doing project planning with a fast and effective plain-text system (as the Org manual says).

Worg is a collectively-built knowledge database about Org, planning in plain text, and other related topics.

Why use Org-mode for creating a collaborative website?

Because Org makes it easy, fast and effective to edit well-structured files. Ever wanted to edit a table in a wiki? Ever wanted to change the outline structure in a wikipage? Ever wanted to edit lists quickly? Org lets you do this.

Because Org-mode makes beautiful documents: it supports links, font beautification, examples, etc. And you can export those documents to HTML, LaTeX, or DocBook.

Because Org is also a powerful task-management system. Hopefully sharing a TODO file will make it easy for everyone to know where he could help.

So Worg is a bit like a wiki, no?

No. Yes. Kind of. Here are a few differences:

  • you edit the pages using Emacs, not a cheesy web interface;
  • the Worg website (repository) is maintained using git;
  • even if people are invited to merge their changes into the main Worg website, they are free to start a new Worgie of their own. Using git makes Worg a distributed community website.
  • there is an important difference: Org is a very fast and effective plain text task-management system. Meaning that you can add the Worg todo file (todo.org in the Worg directory) to your org-agenda-files and see your list of task populated by tasks added by other people…

So what is contained in Worg?

Everything related to Org, project planning in plain text, and the Org community. Go crazy!

Who can participate in the editing of Worg?

Everyone with a minimal knowledge of Org (and Emacs) and git. See the section describing How to use git for Worg for details.

Do I need to register somewhere?

You just need to send your requested username to Timothy, he will create an account on code.orgmode.org for you — see How to use git for Worg for more information.

Who's in charge of Worg?

Worg was started by Bastien in the hope that other Org-ers around will bite into this and start sharing tutorials, example of codes, etc.

Worg is currently maintained by Krupal and Corwin Brust.

Their role is to take care of the Worg repository and to empower new maintainers and contributors.

OK, I want to contribute to Worg now!

The first thing you need to know is review How to use git for Worg.

The second thing you might be interested in is general advice and conventions on how to let Worg grow.

If you're interested in knowing how Worg publishes itself as a website, check the Worg setup page.

If or once you are familiar with the above, you can contribute by sending patches against the Worg repository to the Org mailing list.

~$ git clone https://code.orgmode.org/bzg/worg.git

If you want to contribute regularily, you can ask for commit access. When you get it, you can clone the repository like this:

~$ git clone git@code.orgmode.org:bzg/worg.git

and push commits directly.

How to use git for Worg

What is git?

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 git tutorial. For details on the public git repository, please check it here.

The homepage of the Worg project is here: https://orgmode.org/worg/.

To clone a read-only copy of the repo:

~$ git clone https://code.orgmode.org/bzg/worg.git

If you intend to push changes, see below to ask for an account; and, then clone like this:

~$ git clone git@code.orgmode.org:bzg/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

If you want to contribute to Worg, keep reading.

The first time you contribute to Worg

  1. If you don't have a SSH-key, create one.
  2. Create an account on https://code.orgmode.org by emailing your requested username to Timothy.
  3. Add your public key on this account.
  4. Install git on your system. Tell git to use your private key with worg by updating ~/.ssh/config with:

    Host code.orgmode.org
         HostName code.orgmode.org
         IdentityFile ~/.ssh/your-private-ssh-key-file-name
  5. Clone the project somewhere in a working directory:

    ~$ git clone git@code.orgmode.org:bzg/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. Ask bzg AT gnu.org to be added as a collaborator on the Worg repo.
  10. When you are a collaborator, push your change to Worg:

    ~$ git push

    The system is designed for immediate updates – if not, it means something is wrong. You should be able to read the error message and see what is wrong, then help with fixing issues. In general the issues are trivial to fix.

The second time you contribute to Worg

  1. Go to your worg/ directory.
  2. Be sure to "pull" the last version of the repository.

    ~$ git pull --rebase
  3. Make some changes. (If you want to learn more about various git workflow, read 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 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/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 global ~/.gitconfig file, or in Worg/.git/config.

    Edit it like this:

           name = FirstName LastName
           email = you@yourdomain.example.com

    Now your changes will be filed under your name.

  • Rebase to avoid merging commits

    It's good practice to pull the current version of the repository before making your own additions. But even if you do, someone might make a change while you are working. So it will often be necessary to pull immediately before pushing your new commit. In this situation, if you use git pull directly, then a 'merge commit' will be generated, looking like this:

    commit aaaabbbbbbbbbaaaaaaaaabbbbbbbb
    Merge: bababa efefefef
    Author: Some one <name@domain>
    Date:   Wed Nov 24 00:00:01 2010 -0700
        Merge branch 'master' of git@code.orgmode.org:bzg/worg.git

    That's not a major problem, but it's nice to keep the commit logs free of this stuff. To avoid generating the merge commit, use the --rebase option when pulling:

    ~$ git pull --rebase

    Basically this means that your commit will be put to the top of the stack, as if no one had made any additions while you were working. More advanced git users might make their changes in a personal branch, and then rebase that branch against a freshly pulled master branch before merging it in to master. The end result would be the same as pulling with --rebase.

  • 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 this page.

  • Emacs' in-built version control system and git

    Emacs's VC supports many common git operations, but others, like repository syncing must be done from the command line. For example the Command C-x v v does check in changes in the local and not in the remote repository in contrast to other back ends like svn. It is necessary to do additionally

    ~$ git push

    to sync the change on the remote server.

Something went wrong

Preventing publishing errors

Locally export any document you edit as HTML (C-c C-e h H) prior to committing it to Worg and ensure the export process doesn't fail. This will be more reliable if you're running the latest version of Org.

You may also want to check the formatting in a browser before committing your change (C-c C-e h o).

Troubleshooting publishing errors

If you notice Worg isn't updating, visit publishing.txt and look for the export error near the bottom to find the file where publishing stopped. Locally update to the latest version of Org, open that file, and try reproducing the export error (C-c C-e h H). If it's not obvious where the problem is, look at the most recent changes to the file in question:

cd Worg
git log -p org-quotes.org

Try reverting some of those changes and then re-test exporting (C-c C-e h H).

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.