pifty
/
tutes-dump
Archived
1
1
Fork 1
This repository has been archived on 2020-07-15. You can view files and clone it, but cannot push or open issues or pull requests.
tutes-dump/site-tutorials/scmgit-intro.html

360 lines
13 KiB
HTML

<html>
<head>
<title>scmgit basics</title>
</head>
<body>
<h2>Introduction</h2>
<p>git is a <a href="http://en.wikipedia.org/wiki/Revision_control">source control management</a> tool similiar to CVS or SVN. This tutorial will give enough information to:
<ul>
<li>create a central git repository on your MetaARPA account</li>
<li>clone that git repository to your off-site computer</li>
<li>sync your changes with your repository copy on sdf</li>
<li>create a public readonly copy of your repository</li>
</ul>
The best reason why a person would use git instead of cvs or svn is that git does not require a central server. For example, let's say you were taking out a CVS repository to your laptop and would not be able to connect to the server for a month. When you get back, that entire months worth of work is seen as a single diff. Which you would have to merge by hand to the other changes, but also you couldn't differentiate between reasons you changed files. For example, let's say you fixed a bug and added a new feature. Which filechanges were for the new feature? Which for the bugfix? CVS has no clue. Enter git. You can locally "commit" changes without talking to the server, so you could have done a commit after the new feature and a commit after the bug fix and to the repository they are two unique changes.
<h2>Configuring your account to use git on sdf</h2>
<p>First, you must be MetaARPA to use git.</p>
<p>
Second, it may be necessary to update your <code>$PATH</code> on the main cluster to include git. The git pkg installs most binaries you need in /usr/pkg/libexec/git-core. This needs to be in your PATH. The easiest solution is to include the following in your <code>~/.profile</code>:</p>
<p><code>export PATH=/usr/pkg/libexec/git-core/:${PATH}</code></p>
<p>If this is necessary and you plan on accessing the repository remotely over SSH, be sure this is done even on non-login shells. This may require including it in .kshrc, .bashrc, .zshenv, .cshrc, etc.</p>
<p>Now any SSH session will have the necessary git binaries in the PATH.</p>
<h2>Creating a central git repository on SDF</h2>
I suggest creating a subdirectory that will hold nothing but your git repositories.. let's say it's ~/git.
The server copy of the git repository need not be a useable repository (IE, the files under revision control
do not need to exist.. we just need the git database to exist so we can clone from it). Under git this is
called a "bare" repository.
<h3>Create the server repository</h3>
<p>
<pre>
mkdir -p ~/git/myproject
cd ~/git/myproject
git --bare init
</pre>
</p>
<p>Note that the path is arbitrary and can be anywhere in your home directory. This can be done either on the Meta Array or on the main cluster.</p>
<p>And that's it! on the server side. This remains empty until you first "push" your project to the server.</p>
<h2>Creating your local git repository.</h2>
<p>On your local machine, let's assume you already have a project you want to start watching under git, with the files</p>
<p>
<ul>
<li><code>~/proj/</code></li>
<li><code>~/proj/include</code></li>
<li><code>~/proj/test.c</code></li>
<li><code>~/proj/include/test.h</code></li>
</ul>
</p>
<p>First, initialize the git project:</p>
<p>
<pre>
cd ~/proj
git init
</pre>
</p>
<p> Now your repository is initialized! Time to check in your current project. First we add the files to the repository. I like to manually add each file instead of doing a "commit all" because "commit all" tends to collect files you never wanted to add to source control (object files, temp editing files, etc).</p>
<p>
<pre>
git add test.c include/test.h
git commit
</pre>
</p>
<p>If the commit failed, follow the directions onscreen to configure your username and email so git can track you as a user in the repository.</p>
<p>Now time to connect your local copy to the repository on the main cluster:</p>
<p>
<pre>
git remote add origin user@sdf.org:git/proj
git push origin master
</pre>
</p>
<p>Or, if you created your repo on the Meta Array, set up your remotes like this:</p>
<p>
<pre>
git remote add origin user@ma.sdf.org:git/proj
git push origin master
</pre>
</p>
<p>Git should ask for your password, and then tell you it uploaded the objects and that everything succeeded.<br />
If not, ask on the sdf forum for advise.</p>
<h2>Copying (cloning) your central repository to a client machine</h2>
<p>Last thing: Now that you have a central copy, how do you check it out? use <code>git clone</code> from your local machine:</p>
<p><code>git clone ssh://user@sdf.org/~/git/proj</code></p>
<p>If your repo was created on the Meta Array, adjust accordingly:</p>
<p><code>git clone ssh://user@ma.sdf.org/~/git/proj</code></p>
<h2>Backing up all your existing git repos to a remote server</h2>
sdf doesn't backup your git repository.. while any cloned git tree is basically a backup it'd be nice to have an "official" backup to go along with your now "official" git server on sdf.<br />
Here is a script that will, in sequence:
<ul><li>check your git repo for any changes</li>
<li>if changes exist, tar up all your git repo</li>
<li>ftp it to another host</li>
</ul>
The script is expecting you to have a directory called ~/git, and under that directory have your git projects named as ~/git/proj1.git, ~/git/proj2.git, etc. Otherwise modify it as you see fit.
<h3>The script, git-backup.sh</h3>
<PRE>
#!/usr/pkg/bin/bash
cd ~/git
mv git-summary git-summary-old
for i in *.git; do
cd $i
git log --pretty=oneline >> ../git-summary
cd ..
done
diff git-summary git-summary-old
if [ "$?" != "0" ]; then
#tgz up the whole git directory with today's date
cd ..
rm git-latest.tgz
tar -cvzf git-latest.tgz git
ftp ftp.your-host.com &lt;&lt;WOOPWOOPWOOP
cd git-backup
rename git-latest.tgz git-backup.tgz
put git-latest.tgz
quit
WOOPWOOPWOOP
fi
</PRE>
<p>Note: For the FTP to work, edit your ~/.netrc file so that ftp.your-host.com has an entry that looks like:<br />
<PRE>
machine ftp.your-host.com
login your-user-name
password your-password
bin
</PRE>
Also ensure to run "chmod 600 ~/.netrc" to hide your credentials to the rest of the world :). Now add this to your (daily or less) cron tasks with mkcron (MetaARPA only, just like git ;) and enjoy your timely backups!
<h2>Updating your local copy with changes made to the repo</h2>
First, let's note that for git, each repository is equal. This is
unlike older VCS like CVS or Subversion. Now, if you have not
cloned from your SDF repo, do
<p>
<code>
git remote add origin user@sdf.org:git/project
</code>
</p>
where <code>origin</code> is the nickname for the repository
on <code>sdf.org</code>. Then, you do
<p>
<code>
git fetch
</code>
</p>
followed by
<p>
<code>
git merge
</code>
</p>
Git also provides the command <code>git pull</code> to do a fetch
followed by a merge. This is unlike CVS and Subversion,
where <code>update</code> works like <code>pull</code>. The two
commands are provided because your local repo is not meant to be a
copy of the remote, so you need to be able to fetch the remote without
merging it into your local repository.
<h2>Creating a public access, read only repo</h2>
Once you have your repo setup for you to do your work in, you may
have a need to make your work public. Making it public allows
for other users to pull specific version of your project without
having to have development rights. A slight modification to your
repo is needed and some webspace to host it.<br />
<h3>Setup some webspace</h3>
To host a readonly public access version of your repo you will need
to setup some space in your html directory. For our example our public
repo will be accessable at http://user.sdf.org/devel/proj.git<br />
<br />
<code>mkdir ~/html/devel</code>
<br />
<h3>hooks/post-update</h3>
<p>
In your repo directory for the project there is a directory that
contains a set of scripts which are called at different times during
your interaction with git. For more information about the "hooks"
directory check out
<a href="http://www.kernel.org/pub/software/scm/git/docs/githooks.html">githook</a>.
</p>
<p>
The script we will need to modify is post-update. This
script is called after an update has occured on the server side of
your repo.
</p>
<PRE>
#!/bin/sh
#
# File: ~/git/proj.git/hooks/post-update
#
# Description: Called when an update is pushed to the server
#
# Location of your repo on the server
GIT_DIR=/arpa/tz/u/user/git/proj.git
# Location of your public version of the repo
HTTP_DIR=/arpa/tz/u/user/html/devel/proj.git
# Update local repo info
git update-server-info
# Make sure a clean copy is moved
rm -rf $HTTP_DIR
cp -rf $GIT_DIR $HTTP_DIR
chgrp -R nobody $HTTP_DIR
# Directories must have Read and Execute Permissions
# for apache to be able to navigate them.
for d in `find $HTTP_DIR -type d`; do
chmod a+rx $d
done
# Files must have Read Permissions for apache
# to be able to read them.
for f in `find $HTTP_DIR -type f`; do
chmod a+r $f
done
# Display a message on the client side to show
# the action has been performed.
echo "Updated Public Access"
</PRE>
<p>
Now that you have setup this script make sure its executable.
</p>
<code> chmod a+x ~/git/proj.git/hooks/post-update</code>
<p>
You can now run the script directly or wait until you have
committed and pushed an update to your server.
</p>
<h3>Verifying script is run.</h3>
<p>When you push an update to your private development repo,
a new output has been added by our script.
</p>
<PRE>
$ git push
Counting objects: 5, done.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 256 bytes, done.
Total 3 (delta 1), reused 0 (delta 0)
remote: Updated Public Access
To user@sdf.org:git/proj.git
e60a9de..1f8a43f master -> master
$
</PRE>
<p>In the above example there is a new line labled "remote"
which means that during the push, the server produced output.
The line matches the last line in our post-update script. Now
you have two methods of access.
</p>
<b>Private Access:</b> git clone user@sdf.org:~/git/proj.git<br />
<b>Public Readonly Access:</b> git clone http://user.sdf.org/devel/proj.git<br />
<h2>Allowing Multiple Users git Access</h2>
If you want to use your git repo for a group project and need multiple users
access this can be done with the user of SSH Keys.
<h3>Create SSH Key</h3>
The first step is creating an ssh key for a user. On their local machine
generate a key pair and have them send you the public key.
<PRE>
# ssh-keygen -t dsa
Generating public/private dsa key pair.
Enter file in which to save the key (/home/joe/.ssh/id_dsa): /home/joe/.ssh/sdf-dev
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/joe/.ssh/sdf-dev
Your public key has been saved in /home/joe/.ssh/sdf-dev.pub.
The key fingerprint is:
6e:aa:25:bb:2e:ec:ee:93:ff:ef:a1:21:8a:fe:df:fc joe@mypc
The key's randomart image is:
+--[ DSA 1024]----+
|+++.+. |
|=*+ .. =+ |
|*++ . - .. |
|.o ..= S |
| E . S |
| o . o + |
| ++ . |
| + S o |
| +++ |
+-----------------+
# ls /home/joe/.sdf
sdf-dev sdf-dev.pub
</PRE>
<h3>Create a git access script</h3>
The next task is to create a script that runs git's shell command to create an
instance of a shell that only allows git commands. Store this in your home
directory along with all the other scripts and binaries you keep for personal
use.
<PRE>
#!/bin/sh
exec git-shell -c "$SSH_ORIGINAL_COMMAND"
</PRE>
<p>The <code>$SSH_ORIGINAL_COMMAND</code> variable contains the commands
issued with your ssh session (try logging in with <code>ssh localhost ls</code>).
<h3>Add User to Authorized Keys</h3>
The last step is to add the user's public key to your
<code>authorized_keys</code> file. This will be a little different than you
normally would enter one, as we want to force the user to run our git access
script instead of a normal shell. At the end just paste the contents of the
public key as you normally would.
<PRE>
command="/arpa/gm/f/frank/gitaccess.sh",no-port-forwarding,no-agent-forwarding,no-x11-forwarding,no-pty ssh-rsa AAAB3...
</PRE>
<p>All the <code>no-*</code> flags disable all other types of ssh access
(Port Forwarding, X11, PTY) so we only get git access and nothing else. Now
if your friend uses your user name and his/her ssh key to connect to your git
server they will be able to clone, pull, commit, etc. just as if they were
you. Make sure they set their global settings in their git client so you can
see your history correctly.
<h2>TODO</h2>
merging/branching<br/>
Best look online for more in-depth tutorials.. I haven't needed these features yet as my projects are all just me, so I don't know how to do it!<br /><br />
</body>
</html>
$Id: scmgit-intro.html,v 1.11 2020/01/01 22:52:17 niro Exp $