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