worg-git.org

   1 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   2 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   3 #+TITLE:      How to use git to edit Worg files?
   4 #+AUTHOR:     Worg people
   5 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   6 #+EMAIL:      bzg AT altern DOT org
   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, go and read the [[http://repo.or.cz/about.html][about page]] of
  19 http://repo.or.cz/.
  20
  21 The homepage of the Worg project is here: http://repo.or.cz/w/Worg.git
  22
  23 * The first time you contribute to Worg
  24
  25 1. If you don't have a SSH-key, [[file:worg-git-ssh-key.org][create one]].
  26
  27 2. Register a [[http://repo.or.cz/m/reguser.cgi][new account]] on the git public repository.
  28
  29 3. Drop an email to [[mailto:bzg%20AT%20altern%20DOT%20org][Bastien]] mentioning your username on repo.or.cz
  30
  31 4. Install git on your system.
  32
  33 5. Clone the project somewhere in a working directory:
  34
  35    :~$ git clone git+ssh://repo.or.cz/srv/git/Worg.git
  36
  37 6. Go to the newly created =Worg/= directory and edit some files.
  38
  39 7. If you created files, add them to the git index:
  40
  41    :~$ git add *.org
  42
  43 8. Commit changes with the appropriate ChangeLog:
  44
  45   :~$ git commit -a -m "My changelog"
  46
  47 9. Push your change to Worg:
  48
  49   :~$ git push
  50
  51   This stage didn't work for me, instead I had to add a remote like
  52   so:
  53
  54   :~$ git remote add public git+ssh://<UserName>@repo.or.cz/srv/git/Worg.git
  55
  56   Where <UserName> is the username you supplied repo.or.cz.  Then do
  57   a:
  58
  59   :~$ git push public
  60
  61 * How Worg publishes itself as HTML?
  62
  63   The server behind http://orgmode.org website takes care of publishing
  64   Worg into =HTML=.  This is done in two steps: the first step is to
  65   pull the Worg directly on the server, the second one is to publish the
  66   last version of Worg on the website.  Both steps are cron'ed every
  67   hour, the first one at 1:00, 2:00, etc. and the second one at 1:30,
  68   2:30.
  69
  70   So for example, if you push a change in Worg at 0:58am, this will be
  71   pulled on the server at 1am and will appear on the website at 1:30am.
  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 3. Make some changes.
  80
  81 4. Commit your changes on your local repository:
  82
  83    :~$ git commit -a -m "My ChangeLog"
  84
  85 5. Push your change on the remote repository
  86
  87    :~$ git push
  88
  89 * Getting organized
  90
  91 The Worg TODO file is =worg-todo.org=.  If you are a Worg zealot, maybe you
  92 want to add this file to the list of your agenda files.  For example, here
  93 is my =org-agenda-files= variable:
  94
  95   :(setq org-agenda-files '("~/org/bzg.org" "~/git/Worg/worg-todo.org")
  96
  97 I have an agenda custom command for checking tasks that are assigned to me:
  98
  99   :(org-add-agenda-custom-command '("W" tags "Owner=\"Bastien\""))
 100
 101 The next time someone assigns a task for me, it will appear in my Worg
 102 agenda view.
 103
 104 * Register your changes under your name
 105
 106 Information regarding your name is stored in the .gitconfig file, where
 107 you pulled the Worg project.
 108
 109 Edit it like this:
 110
 111 :[user]
 112 :        name = Your Name Goes Here
 113 :        email = you@yourdomain.example.com
 114
 115 Now your changes will be filed under your name.
 116
 117 Alternatively you can add this to ~/.gitconfig which will apply to all
 118 git repositories you have.
 119
 120 # I'm not sure this is useful at all:
 121 * COMMENT Anonymous editing through the "mob" user/branch
 122
 123 If you don't want to register a new account on =repo.or.gz= but still
 124 want to suggest modifications on Worg, you can do this by editing the
 125 "mob" branch of Worg.  For details about the =mob= user, check [[http://repo.or.cz/mob.html][this
 126 webpage]] on repo.or.cz
 127
 128 This branch is usually empty, since interesting changes are quickly
 129 merged into the master branch.  But it is important to make sure that
 130 you pull all changes in any existing =mob= branch before trying to push
 131 yours.
 132
 133 1. Clone the Worg project as the =mob= user:
 134
 135    :~$ git clone git+ssh://mob@repo.or.cz/srv/git/Worg.git
 136
 137 2. Check out the "mob" branch to avoid conflicts between the =mob=
 138    branch that you will soon create and any existing =mob= branch:
 139
 140    :~$ git checkout origin/mob
 141
 142    You should get this warning:
 143
 144    : Note: moving to "origin/mob" which isn't a local branch
 145    : If you want to create a new branch from this checkout, you may do so
 146    : now or later) by using -b with the checkout command again. Example:
 147    : git checkout -b <new_branch_name>
 148
 149    Don't worry.
 150
 151 3. Create a new branch named =mob= from this checkout:
 152
 153    :~$ git checkout -b mob
 154
 155 4. Edit the files, add new files (=git-add=) and commit (=git-commit=)
 156    them as usual.
 157
 158 5. Push the =mob= branch into the Worg remote directory:
 159
 160    :~$ git push origin mob
 161
 162 You're done!
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177 # FIXME:
 178 # What if two people edit Worg at the same time?
 179 # Can I have private sections in Worg?