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