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