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:      bzg AT altern 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
  33
  34 If you want to contribute to Worg, keep reading.
  35
  36 * The first time you contribute to Worg
  37   :PROPERTIES:
  38   :CUSTOM_ID: contribute-to-worg
  39   :END:
  40
  41
  42 1. If you don't have a SSH-key, [[file:worg-git-ssh-key.org][create one]].
  43
  44 2. Register a [[http://repo.or.cz/reguser.cgi][new account]] on the git public repository (don't forget to
  45    copy paste your public SSH key from =~/.ssh/id_rsa.pub= to the
  46    registration form.)
  47
  48 3. *Drop an email to* [[mailto:bzg%20AT%20altern%20DOT%20org][Bastien]] mentioning your username on repo.or.cz.
  49
  50 4. Install git on your system.
  51
  52 5. Clone the project somewhere in a working directory:
  53
  54    - If your user name in the shell is the same as the =Login=
  55      [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:
  56
  57      : ~$ git clone git+ssh://repo.or.cz/srv/git/Worg.git
  58
  59    - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:
  60
  61      : ~$ git clone git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
  62
  63 6. Go to the newly created =Worg/= directory and edit some files.
  64
  65 7. If you created files, add them to the git index:
  66
  67    : ~$ git add *.org
  68
  69 8. Commit changes with the appropriate comment:
  70
  71    : ~$ git commit -a -m "summary comment about all changes"
  72
  73 9. Push your change to Worg:
  74
  75    - If your user name in the shell is the same as the
  76      =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]]:
  77
  78      : ~$ git push
  79
  80    - else add the =Login= [[http://repo.or.cz/reguser.cgi][registered at repo.or.cz]] to <UserName>:
  81
  82      : ~$ git remote add public git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
  83
  84      Then do a:
  85
  86      : ~$ git push public
  87
  88      If you get a git error message looking like the one at the bottom
  89      of this page, then this means that you've forgotten to drop a mail
  90      to Bastien (see step 3).
  91
  92 * The second time you contribute to Worg
  93
  94 1. Go to your =Worg/= directory.
  95
  96 2. Be sure to "pull" the last version of the repository.
  97
  98 3. Make some changes.  (If you want to learn more about various git
  99    workflow, read [[file:worg-git-advanced.org][this page]].)
 100
 101 4. Commit your changes on your local repository:
 102
 103    : ~$ git commit -a -m "summary comment about all changes"
 104
 105 5. Push your change on the remote repository
 106
 107    : ~$ git push
 108
 109 * Going deeper
 110 ** Getting organized
 111
 112 The Worg TODO file is =worg-todo.org=.  If you are a Worg zealot, maybe you
 113 want to add this file to the list of your agenda files.  For example, here
 114 is my =org-agenda-files= variable:
 115
 116   : (setq org-agenda-files '("~/org/bzg.org" "~/git/Worg/worg-todo.org")
 117
 118 I have an agenda custom command for checking tasks that are assigned to me:
 119
 120   : (org-add-agenda-custom-command '("W" tags "Owner=\"Bastien\""))
 121
 122 The next time someone assigns a task for me, it will appear in my Worg
 123 agenda view.
 124
 125 ** Register your changes under your name
 126
 127 Information regarding your name can be stored in your ~/.gitconfig file.
 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 ** Dealing with line endings
 140
 141 Unix, Windows and Mac all have different conventions for marking
 142 the end of a line. This might lead to problems when editing the
 143 same file across platforms. Github advises Linux users to
 144 automatically convert all external files to LF on committing (see
 145 [[http://help.github.com/dealing-with-lineendings]]) by setting:
 146 : $ git config --global core.autocrlf input
 147 For Worg, this is the wrong solution, since there are already
 148 files with both end of line conventions in the repository.
 149 Instead tell git locally not to convert files by setting:
 150 : $ git config core.autocrlf false
 151 Of course you have to be careful not to save Windows files as
 152 Unix files or vice versa, since this would lead to large and
 153 confusing diffs. This should not be a problem with Worg as
 154   - one rarely edits other people's files anyway, and
 155   - Emacs can deal with end of line conventions transparently.
 156
 157 ** Git usage for people who just want to send patches
 158
 159 See [[file:worg-git-advanced.org][this page]].
 160
 161 * COMMENT Anonymous editing through the "mob" user/branch
 162
 163 If you don't want to register a new account on =repo.or.gz= but still
 164 want to suggest modifications on Worg, you can do this by editing the
 165 "mob" branch of Worg.  For details about the =mob= user, check [[http://repo.or.cz/mob.html][this
 166 webpage]] on repo.or.cz
 167
 168 This branch is usually empty, since interesting changes are quickly
 169 merged into the master branch.  But it is important to make sure that
 170 you pull all changes in any existing =mob= branch before trying to push
 171 yours.
 172
 173 1. Clone the Worg project as the =mob= user:
 174
 175    : ~$ git clone git+ssh://mob@repo.or.cz/srv/git/Worg.git
 176
 177 2. Check out the "mob" branch to avoid conflicts between the =mob=
 178    branch that you will soon create and any existing =mob= branch:
 179
 180    : ~$ git checkout origin/mob
 181
 182    You should get this warning:
 183
 184    : Note: moving to "origin/mob" which isn't a local branch
 185    : If you want to create a new branch from this checkout, you may do so
 186    : now or later) by using -b with the checkout command again. Example:
 187    : git checkout -b <new_branch_name>
 188
 189    Don't worry.
 190
 191 3. Create a new branch named =mob= from this checkout:
 192
 193    : ~$ git checkout -b mob
 194
 195 4. Edit the files, add new files (=git-add=) and commit (=git-commit=)
 196    them as usual.
 197
 198 5. Push the =mob= branch into the Worg remote directory:
 199
 200    : ~$ git push origin mob
 201
 202 You're done!
 203
 204 # FIXME:
 205
 206 # What if two people edit Worg at the same time?
 207 # bzg [2009-07-15 mer]: No problem.  Just try to push and resolve
 208 # conflicts if any.
 209
 210 # Can I have private sections in Worg?
 211 # bzg [2009-07-15 mer]: Sure.  Just add an :AUTHOR: property in
 212 # the property drawer.
 213
 214 * Example error message
 215
 216 Git error message, when you don't have push permissions to Worg:
 217
 218        : % git push
 219        : Counting objects: 5, done.
 220        : Delta compression using up to 2 threads.
 221        : Compressing objects: 100% (3/3), done.
 222        : Writing objects: 100% (3/3), 463 bytes, done.
 223        : Total 3 (delta 2), reused 0 (delta 0)
 224        : error: unable to create temporary sha1 filename ./objects/64: File exists
 225        :
 226        : fatal: failed to write object
 227        : error: unpack failed: unpacker exited with error code
 228        : To git+ssh://myUserName@repo.or.cz/srv/git/Worg.git
 229        :  ! [remote rejected] master -> master (n/a (unpacker error))
 230        : error: failed to push some refs to
 231        :   'git+ssh://myUserName@repo.or.cz/srv/git/Worg.git'
 232