worg/worg-git.org

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, go and read the 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, .

1. Register a 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.)

1. Drop an email to Matt Lundin mentioning your username on repo.or.cz.

1. Install git on your system.

1. 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 registered at repo.or.cz to :

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

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

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

~$ git add *.org

1. Commit changes with the appropriate comment:

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

1. 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 registered at repo.or.cz to :

~$ git remote add public git+ssh://@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.

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

~$ git pull --rebase

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

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

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

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


Don't worry.


Create a new branch named mob from this checkout:

~$ git checkout -b mob



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



Push the mob branch into the Worg remote directory:


~$ git push origin mob


You're done!








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'