How to use git to edit Worg files?

What is git?
The first time you contribute to Worg
The second time you contribute to Worg
Going deeper

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: http://orgmode.org/w/worg.git. You can get a read-only clone of the repository with the command:

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

If you don't have a SSH-key, create one.
Send your public key to Jason or Bastien asking for push access and wait for confirmation that you have push access.
Install git on your system.
Clone the project somewhere in a working directory:
```
~$ git clone worg@orgmode.org:worg.git
```
If you already have your local clone of Worg obtained via http protocol, you can easily tell your git to remain using http for fetching and git for pushing, by adding to your ~/.gitconfig:
```
[url "git://worg@orgmode.org:worg.git"]
  pushInsteadOf = http://repo.or.cz/r/
```
which could come handy later on for any project you clone from http://repo.or.cz
Go to the newly created worg/ directory and edit some files.
If you created files, add them to the git index:
```
~$ git add *.org
```

Commit changes with the appropriate comment:

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

Push your change to Worg:
```
~$ git push
```

The second time you contribute to Worg

Go to your worg/ directory.
Be sure to "pull" the last version of the repository.
```
~$ git pull --rebase
```
Make some changes. (If you want to learn more about various git workflow, read this page.)

Commit your changes on your local repository:

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

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 global ~/.gitconfig file, or in Worg/.git/config.

Edit it like this:

[user]
       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+ssh://repo.or.cz/srv/git/Worg

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.