worg-git.org

   1 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   2 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   3 #+TITLE:      How to use git to edit Worg files?
   4 #+AUTHOR:     Worg people
   5 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   6 #+EMAIL:      mdl AT imapmail DOT org
   7 #+LANGUAGE:   en
   8 #+PRIORITIES: A C B
   9 #+CATEGORY:   worg
  10 #+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
  11
  12 [[file:index.org][{Back to Worg's index}]]
  13
  14 * What is git?
  15
  16 [[http://git.or.cz][git]] is a fast version control system that lets you collaborate on a project.
  17 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
  18 the public git repository, go and read the [[http://repo.or.cz/about.html][about page]] of
  19 http://repo.or.cz/.
  20
  21 The homepage of the Worg project is here: http://repo.or.cz/w/Worg.git
  22 You can get a read-only clone of the repository with the command:
  23
  24    : ~$ git clone http://repo.or.cz/r/Worg.git
  25
  26 Since Worg is constantly updated you may want to update your copy
  27 of Worg before reading sometimes later.  To do so cd into the
  28 Worg directory and upgrade your copy of Worg with the command:
  29
  30    : ~$ git pull http://repo.or.cz/r/Worg.git
  31
  32 If you want to contribute to Worg, keep reading.
  33
  34 * The first time you contribute to Worg
  35   :PROPERTIES:
  36   :CUSTOM_ID: contribute-to-worg
  37   :END:
  38
  39 1. If you don't have a SSH-key, [[file:worg-git-ssh-key.org][create one]].
  40
  41 2. Register a [[http://repo.or.cz/reguser.cgi][new account]] on the git public repository (don't forget to
  42    copy paste your public SSH key from =~/.ssh/id_rsa.pub= to the
  43    registration form.)
  44
  45 3. *Drop an email to* [[mailto:mdl%20AT%20imapmail%20DOT%20org][Matt Lundin]] mentioning your username on repo.or.cz.
  46
  47 4. Install git on your system.
  48
  49 5. Clone the project somewhere in a working directory:
  50
  51    - If your user name in the shell is the same as the =Login=
  52      [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:
  53
  54      : ~$ git clone git+ssh://repo.or.cz/srv/git/Worg.git
  55
  56    - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:
  57
  58      : ~$ git clone git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
  59
  60 6. Go to the newly created =Worg/= directory and edit some files.
  61
  62 7. If you created files, add them to the git index:
  63
  64    : ~$ git add *.org
  65
  66 8. Commit changes with the appropriate comment:
  67
  68    : ~$ git commit -a -m "summary comment about all changes"
  69
  70 9. Push your change to Worg:
  71
  72    - If your user name in the shell is the same as the
  73      =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:
  74
  75      : ~$ git push
  76
  77    - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:
  78
  79      : ~$ git remote add public git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
  80
  81      Then do a:
  82
  83      : ~$ git push public
  84
  85      If you get a git error message looking like the one at the bottom
  86      of this page, then this means that you've forgotten to drop a mail
  87      to Matt (see step 3).
  88
  89 * The second time you contribute to Worg
  90
  91 1. Go to your =Worg/= directory.
  92
  93 2. Be sure to "pull" the last version of the repository.
  94
  95   : ~$ git pull --rebase
  96
  97 3. Make some changes.  (If you want to learn more about various git
  98    workflow, read [[file:worg-git-advanced.org][this page]].)
  99
 100 4. Commit your changes on your local repository:
 101
 102    : ~$ git commit -a -m "summary comment about all changes"
 103
 104 5. Push your change on the remote repository
 105
 106    : ~$ git push
 107
 108 * Going deeper
 109 ** Getting organized
 110
 111 The Worg TODO file is =worg-todo.org=.  If you are a Worg zealot, maybe you
 112 want to add this file to the list of your agenda files.  For example, here
 113 is my =org-agenda-files= variable:
 114
 115   : (setq org-agenda-files '("~/org/bzg.org" "~/git/Worg/worg-todo.org")
 116
 117 I have an agenda custom command for checking tasks that are assigned to me:
 118
 119   : (org-add-agenda-custom-command '("W" tags "Owner=\"Bastien\""))
 120
 121 The next time someone assigns a task for me, it will appear in my Worg
 122 agenda view.
 123
 124 ** Register your changes under your name
 125
 126 Information regarding your name can be stored in your global
 127 ~/.gitconfig file, or in Worg/.git/config
 128
 129 Edit it like this:
 130
 131 : [user]
 132 :        name = FirstName LastName
 133 :        email = you@yourdomain.example.com
 134
 135 Now your changes will be filed under your name.
 136
 137 # I'm not sure this is useful at all:
 138
 139 ** Rebase to avoid merging commits
 140    It's good practice to pull the current version of the repository
 141    before making your own additions. But even if you do, someone might
 142    make a change while you are working. So it will often be necessary
 143    to pull immediately before pushing your new commit. In this
 144    situation, if you use 'git pull' directly, then a 'merge commit'
 145    will be generated, looking like this:
 146
 147 #+begin_example
 148 commit aaaabbbbbbbbbaaaaaaaaabbbbbbbb
 149 Merge: bababa efefefef
 150 Author: Some one <name@domain>
 151 Date:   Wed Nov 24 00:00:01 2010 -0700
 152
 153     Merge branch 'master' of git+ssh://repo.or.cz/srv/git/Worg
 154 #+end_example
 155
 156    That's not a major problem, but it's nice to keep the commit logs
 157    free of this stuff. To avoid generating the merge commit, use the
 158    =--rebase= option when pulling:
 159
 160   : ~$ git pull --rebase
 161
 162    Basically this means that your commit will be put to the top of the
 163    stack, as if no one had made any additions while you were
 164    working. More advanced git users might make their changes in a
 165    personal branch, and then rebase that branch against a freshly
 166    pulled master branch before merging it in to master. The end result
 167    would be the same as pulling with =--rebase=.
 168
 169 ** Dealing with line endings
 170
 171 Unix, Windows and Mac all have different conventions for marking
 172 the end of a line. This might lead to problems when editing the
 173 same file across platforms. Github advises Linux users to
 174 automatically convert all external files to LF on committing (see
 175 [[http://help.github.com/dealing-with-lineendings]]) by setting:
 176 : $ git config --global core.autocrlf input
 177 For Worg, this is the wrong solution, since there are already
 178 files with both end of line conventions in the repository.
 179 Instead tell git locally not to convert files by setting:
 180 : $ git config core.autocrlf false
 181 Of course you have to be careful not to save Windows files as
 182 Unix files or vice versa, since this would lead to large and
 183 confusing diffs. This should not be a problem with Worg as
 184   - one rarely edits other people's files anyway, and
 185   - Emacs can deal with end of line conventions transparently.
 186
 187 ** Git usage for people who just want to send patches
 188
 189 See [[file:worg-git-advanced.org][this page]].
 190
 191 * COMMENT Anonymous editing through the "mob" user/branch
 192
 193 If you don't want to register a new account on =repo.or.gz= but still
 194 want to suggest modifications on Worg, you can do this by editing the
 195 "mob" branch of Worg.  For details about the =mob= user, check [[http://repo.or.cz/mob.html][this
 196 webpage]] on repo.or.cz
 197
 198 This branch is usually empty, since interesting changes are quickly
 199 merged into the master branch.  But it is important to make sure that
 200 you pull all changes in any existing =mob= branch before trying to push
 201 yours.
 202
 203 1. Clone the Worg project as the =mob= user:
 204
 205    : ~$ git clone git+ssh://mob@repo.or.cz/srv/git/Worg.git
 206
 207 2. Check out the "mob" branch to avoid conflicts between the =mob=
 208    branch that you will soon create and any existing =mob= branch:
 209
 210    : ~$ git checkout origin/mob
 211
 212    You should get this warning:
 213
 214    : Note: moving to "origin/mob" which isn't a local branch
 215    : If you want to create a new branch from this checkout, you may do so
 216    : now or later) by using -b with the checkout command again. Example:
 217    : git checkout -b <new_branch_name>
 218
 219    Don't worry.
 220
 221 3. Create a new branch named =mob= from this checkout:
 222
 223    : ~$ git checkout -b mob
 224
 225 4. Edit the files, add new files (=git-add=) and commit (=git-commit=)
 226    them as usual.
 227
 228 5. Push the =mob= branch into the Worg remote directory:
 229
 230    : ~$ git push origin mob
 231
 232 You're done!
 233
 234 # FIXME:
 235
 236 # What if two people edit Worg at the same time?
 237 # bzg [2009-07-15 mer]: No problem.  Just try to push and resolve
 238 # conflicts if any.
 239
 240 # Can I have private sections in Worg?
 241 # bzg [2009-07-15 mer]: Sure.  Just add an :AUTHOR: property in
 242 # the property drawer.
 243
 244 * Example error message
 245
 246 Git error message, when you don't have push permissions to Worg:
 247
 248        : % git push
 249        : Counting objects: 5, done.
 250        : Delta compression using up to 2 threads.
 251        : Compressing objects: 100% (3/3), done.
 252        : Writing objects: 100% (3/3), 463 bytes, done.
 253        : Total 3 (delta 2), reused 0 (delta 0)
 254        : error: unable to create temporary sha1 filename ./objects/64: File exists
 255        :
 256        : fatal: failed to write object
 257        : error: unpack failed: unpacker exited with error code
 258        : To git+ssh://myUserName@repo.or.cz/srv/git/Worg.git
 259        :  ! [remote rejected] master -> master (n/a (unpacker error))
 260        : error: failed to push some refs to
 261        :   'git+ssh://myUserName@repo.or.cz/srv/git/Worg.git'
 262