git-howto.txt

   1 This little howto is about the Git repository used by Titanium Linux.
   2 You will find here examples of the most common git commands.
   3
   4 Ready? Let's start (you must have RW access to TLD git repositories).
   5
   6 Table Of Content:
   7 1. How do I prepare git to work?
   8    a) Install git-core
   9    b) Configure git globally
  10    c) Configure ssh environment to work with git
  11 2. How do I commit a new .spec file or package to the repository?
  12    a) Clone an empty repository (note: it will be automatically created on server
  13       side.)
  14    b) Set your local Email address
  15    c) Put your files into the repository and add them locally
  16    d) Push your changes to the server
  17 3. Crap, I've checked out a repository, forgot to change the local e-mail
  18    address and commited my changes. Now I can't push them to the server.
  19    What can I do?
  20 4. My new repository didn't show up on the web.
  21 5. I've deleted some files in my cloned repo. I'm doing git pull, but they
  22    do not reappear.
  23 6. How can I add a description to a new repository?
  24 7. SPECS: What is obsolete now that we have GIT?
  25
  26 ==============================================================================
  27 1. How do I prepare git to work?
  28
  29 a) Install git-core
  30
  31 Just install git-core package via poldek:
  32
  33 poldek
  34 install git-core
  35
  36 b) Configure git globally
  37
  38 To be able to work with git on TLD repository you will need to set up few
  39 things in git config:
  40
  41 - your e-mail address which consists of your git login and tld-linux.org domain
  42 - your username, which should consist of your name and surename
  43
  44 To do so, type:
  45
  46 git config --global user.email "your_git_login@tld-linux.org"
  47 git config --global user.name "John Doe"
  48
  49 Replace "your_git_login" and "John Doe" accordingly.
  50
  51 Above commands will create ~/.gitconfig file with proper settings.
  52
  53 c) Configure ssh environment to work with git
  54
  55 If you plan to use non default ssh key pair, it's better to put some info about
  56 it to your default .ssh/config file. Edit your local Host alias and key path in
  57 sample below:
  58
  59 Host git.tld-linux.org
  60      User git
  61      Hostname git.tld-linux.org
  62      PreferredAuthentications publickey
  63      IdentityFile /home/users/YOURUSER/.ssh/YOUR_KEY_FILE
  64
  65 To test if ssh works, do the:
  66
  67 ssh -T git.tld-linux.org
  68
  69 you should get similar answer:
  70
  71 hello USER, the gitolite version here is x.y.z
  72 the gitolite config gives you the following access:
  73      R   W      TLD
  74         (...)
  75
  76 ==============================================================================
  77 2. How do I commit a new .spec file or package to the repository?
  78
  79 a) Clone an empty repository (note: it will be automatically created on server
  80    side.)
  81
  82 git clone git@git.tld-linux.org:packages/your_new_package
  83
  84 b) Set your local Email address
  85
  86 This step is optional if your git is configured globally (see point 1 of this HOWTO).
  87
  88 cd your_new_package
  89 git config --local user.email your_git_login@tld-linux.org
  90
  91 This step allows you to later push your changes to the server. If you skip
  92 this step, your push will fail due to a server side hook.
  93
  94 c) Put your files into the repository and add them locally
  95
  96 git add file1 file2 files*
  97 git commit
  98
  99 d) Push your changes to the server
 100
 101 If you push your changes for the first time of the repositorys "life", you'll
 102 need to add the origin to it.
 103
 104 git push origin master
 105
 106 After that you'll be fine by doing just:
 107
 108 git push
 109
 110 NOTE:
 111
 112 It is possible to shorten these commands ex. git add and git commit can be put
 113 together into: git commit -a. You can commit several times into your local
 114 repository before pushing all changes to server. You don't need to push each
 115 time you commit, but feel free to do so if you want :-)
 116
 117 ==============================================================================
 118 3. Crap, I've checked out a repository, forgot to change the local e-mail
 119 address and commited my changes. Now I can't push them to the server.
 120 What can I do?
 121
 122 This is very unfortunate. AFAIK you've got only 2 options.
 123
 124 a) Delete your commit. This means all of your changes will be lost, but you
 125 can store them elsewhere for the time being, right?
 126
 127 To do this (after you backed up your changes) type:
 128
 129 git reset --hard HEAD~1
 130
 131 the HEAD~1 option tells git to go 1 commit back in the history. Now set your
 132 local e-mail address, put back your changes and commit again. Push should now
 133 work as expected.
 134
 135 b) The second way is to remove locally your repository and re-clone it. Then
 136 put back your changes to it, commit and push.
 137
 138 ==============================================================================
 139 4. My new repository didn't show up on the web.
 140
 141 Repository "packages" are checked every 15 minutes for new subrepositories by
 142 a cron job. If found, they're added to the web. If for some reason cron job
 143 fails, ask one of the git admins to run and/or fix this script:
 144
 145 ~git/scripts/packages_enable_gitweb.sh
 146
 147 Top level repositores have to be added manually to gitweb. Ask one of the git
 148 admins to do the following:
 149
 150 ssh your_login@kraz.tld-linux.org
 151 sudo su - git
 152 cd ~/repositories/repo_name.git
 153 touch gitweb-export-ok
 154
 155 ==============================================================================
 156 5. I've deleted some files in my cloned repo. I'm doing git pull, but they
 157 do not reappear.
 158
 159 Please do the following in your cloned repo to restore deleted files:
 160
 161 git checkout some.file
 162
 163 To restore all your deleted files do:
 164
 165 git ls-files -d | xargs git checkout --
 166
 167 ==============================================================================
 168 6. How can I add a description to a new repository?
 169
 170 Do the following:
 171
 172 echo "Some description" |ssh git@git.tld-linux.org setdesc packages/some_package
 173
 174 Ex.
 175
 176 $ echo "kernel-desktop, a linux version optimised for the desktop" |ssh git@git.tld-linux.org setdesc packages/kernel-desktop
 177 New description is:
 178 kernel-desktop, a linux version optimised for the desktop
 179 $
 180
 181 ==============================================================================
 182 7. SPECS: What is obsolete now that we have GIT?
 183
 184 Now that we use GIT for our own .spec files and projects, there're some things
 185 we do no longer need.
 186
 187 a) Remove "# $Revision:" lines on top of a .spec file
 188 b) Remove the whole changelog from the bottom of a .spec file
 189 c) Remove "%define date    %(echo `LC_ALL="C" date +"%a %b %d %Y"`)"
 190 d) Remove feedback stuff and all PLD related links
 191 e) Remove all the conditions for pld_release (%if "%{pld_release}" == "ti" ect.)
 192
 193 Why all that removing?
 194 There're a couple of reasons why we don't want to keep these things in our
 195 specs.
 196 Most of them are strictly CVS related, like the Revision stuff. We don't need
 197 to artificially increase the size of our .spec files by having the whole
 198 changelog included in them. Use "git log", with all its sophisticated options,
 199 to visualise changes, make statistics etc.