worg-git.org

   1 #+TITLE:      How to use git to edit Worg files?
   2 #+AUTHOR:     Worg people
   3 #+EMAIL:      mdl AT imapmail DOT org
   4 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   5 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   6 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   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 f:t *:t tex:t d:(HIDE) tags:not-in-toc
  11 #+HTML_LINK_UP:    index.html
  12 #+HTML_LINK_HOME:  https://orgmode.org/worg/
  13
  14 # This file is released by its authors and contributors under the GNU
  15 # Free Documentation license v1.3 or later, code examples are released
  16 # under the GNU General Public License v3 or later.
  17
  18 * What is git?
  19
  20 [[http://git.or.cz][git]] is a fast version control system that lets you collaborate on a
  21 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]].
  22 For details on the public git repository, please check it [[https://code.orgmode.org/bzg/worg][here]].
  23
  24 The homepage of the Worg project is here: https://orgmode.org/worg/.
  25
  26 To clone a read-only copy of the repo:
  27
  28    : ~$ git clone https://code.orgmode.org/bzg/worg.git
  29
  30 If you intend to push changes, see below to ask for an account; and,
  31 then clone like this:
  32
  33    : ~$ git clone git@code.orgmode.org:bzg/worg.git
  34
  35 Since Worg is constantly updated you may want to update your copy of
  36 Worg before reading sometimes later.  To do so =cd= into the Worg
  37 directory and upgrade your copy of Worg with the command:
  38
  39    : ~$ git pull
  40
  41 If you want to contribute to Worg, keep reading.
  42
  43 * The first time you contribute to Worg
  44   :PROPERTIES:
  45   :CUSTOM_ID: contribute-to-worg
  46   :END:
  47
  48 1. If you don't have a SSH-key, [[file:worg-git-ssh-key.org][create one]].
  49
  50 2. Create an account on https://code.orgmode.org by emailing your
  51    requested username to [[mailto:tec@tecosaur.com][Timothy]].
  52
  53 3. Add your public key on this account.
  54
  55 4. Install =git= on your system. Tell =git= to use your private key with
  56    worg by updating =~/.ssh/config= with:
  57
  58      : Host code.orgmode.org
  59      :      HostName code.orgmode.org
  60      :      IdentityFile ~/.ssh/your-private-ssh-key-file-name
  61
  62 5. Clone the project somewhere in a working directory:
  63
  64      : ~$ git clone git@code.orgmode.org:bzg/worg.git
  65
  66 6. Go to the newly created =worg/= directory and edit some files.
  67
  68 7. If you created files, add them to the git index:
  69
  70    : ~$ git add *.org
  71
  72 8. Commit changes with the appropriate comment:
  73
  74    : ~$ git commit -a -m "summary comment about all changes"
  75
  76 9. Ask =bzg AT gnu.org= to be added as a collaborator on the Worg repo.
  77
  78 10. When you are a collaborator, push your change to Worg:
  79
  80       : ~$ git push
  81
  82     The system is designed for immediate updates -- if not, it means
  83     something is wrong.  You should be able to read the error message
  84     and see what is wrong, then help with fixing issues.  In general
  85     the issues are trivial to fix.
  86
  87 * The second time you contribute to Worg
  88
  89 1. Go to your =worg/= directory.
  90
  91 2. Be sure to "pull" the last version of the repository.
  92
  93   : ~$ git pull --rebase
  94
  95 3. Make some changes.  (If you want to learn more about various git
  96    workflow, read [[file:worg-git-advanced.org][this page]].)
  97
  98 4. Commit your changes on your local repository:
  99
 100    : ~$ git commit -a -m "summary comment about all changes"
 101
 102 5. Push your change on the remote repository
 103
 104    : ~$ git push
 105
 106 * Going deeper
 107
 108 ** Getting organized
 109
 110 The Worg TODO file is =worg-todo.org=.  If you are a Worg zealot, maybe
 111 you want to add this file to the list of your agenda files.  For
 112 example, here is my =org-agenda-files= variable:
 113
 114   : (setq org-agenda-files '("~/org/bzg.org" "~/git/worg/worg-todo.org")
 115
 116 I have an agenda custom command for checking tasks that are assigned
 117 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
 141 It's good practice to pull the current version of the repository
 142 before making your own additions. But even if you do, someone might
 143 make a change while you are working. So it will often be necessary to
 144 pull immediately before pushing your new commit. In this situation, if
 145 you use =git pull= directly, then a 'merge commit' will be generated,
 146 looking like this:
 147
 148 #+begin_example
 149 commit aaaabbbbbbbbbaaaaaaaaabbbbbbbb
 150 Merge: bababa efefefef
 151 Author: Some one <name@domain>
 152 Date:   Wed Nov 24 00:00:01 2010 -0700
 153
 154     Merge branch 'master' of git+ssh://repo.or.cz/srv/git/Worg
 155 #+end_example
 156
 157 That's not a major problem, but it's nice to keep the commit logs free
 158 of this stuff. To avoid generating the merge commit, use the =--rebase=
 159 option when pulling:
 160
 161 : ~$ git pull --rebase
 162
 163 Basically this means that your commit will be put to the top of the
 164 stack, as if no one had made any additions while you were
 165 working. More advanced git users might make their changes in a
 166 personal branch, and then rebase that branch against a freshly pulled
 167 master branch before merging it in to master. The end result would be
 168 the same as pulling with =--rebase=.
 169
 170 ** Dealing with line endings
 171
 172 Unix, Windows and Mac all have different conventions for marking the
 173 end of a line. This might lead to problems when editing the same file
 174 across platforms. Github advises Linux users to automatically convert
 175 all external files to LF on committing (see
 176 [[http://help.github.com/dealing-with-lineendings]]) by setting:
 177
 178 : ~$ git config --global core.autocrlf input
 179
 180 For Worg, this is the wrong solution, since there are already files
 181 with both end of line conventions in the repository.  Instead tell git
 182 locally not to convert files by setting:
 183
 184 : ~$ git config core.autocrlf false
 185
 186 Of course you have to be careful not to save Windows files as Unix
 187 files or vice versa, since this would lead to large and confusing
 188 diffs. This should not be a problem with Worg as
 189
 190 - one rarely edits other people's files anyway, and
 191 - Emacs can deal with end of line conventions transparently.
 192
 193 ** Git usage for people who just want to send patches
 194
 195 See [[file:worg-git-advanced.org][this page]].
 196
 197 ** Emacs' in-built version control system and git
 198
 199    Emacs's VC supports many common git operations, but others, like
 200    repository syncing must be done from the command line.  For example
 201    the Command =C-x v v= does check in changes in the *local* and not
 202    in the *remote* repository in contrast to other back ends like svn.
 203    It is necessary to do additionally
 204
 205 : ~$ git push
 206
 207    to sync the change on the remote server.