fabba138e7e02be1a98daff86128429eacd94fa3
[worg.git] / 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 -: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, 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:jasonATdunsmorDOTcom][Jason]] or [[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