#+TITLE:      How to use git to edit Worg files?
#+AUTHOR:     Worg people
#+EMAIL:      mdl AT imapmail DOT org
#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+TAGS:       Write(w) Update(u) Fix(f) Check(c)
#+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, please check it [[http://orgmode.org/w/worg.git][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
  :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. Send your public key to [[mailto:jasonATdunsmorDOTcom][Jason]] or [[mailto:bzgATgnuDOTorg][Bastien]] asking for push access and wait
   for confirmation that you have push access.

4. Install =git= on your system.

5. 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

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:

     : ~$ git push

* 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 [[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 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.

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

** 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:

#+begin_example
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
#+end_example

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 [[file:worg-git-advanced.org][this page]].