[FILE] GNU BIT

From: Andreas Gal <gal@uci.edu>
Date: 2005-04-25 16:24:24
               BIT - a little bit like SCM
   

BIT is a training exercise in shell programming and is the result of
my attempts to wrap my head around GIT's inner working. BIT's
command line interface should be very familiar to anyone who worked
with other(tm) SCM tools before. I try to not depend on custom 
GIT features. BIT uses the off-the-shelf GIT core tools distributed
by Linus. This means that BIT has about 2% of the features of
Cogito. Also, it has about 0.1% of the user base of Cogito, so its
probably very broken and I really don't recommend using it.

You can obtain BIT from the following GIT repository:

http://nil.ics.uci.edu/~gal/public/bit

You can use the GIT core utilities to pull and check-out BIT:

init-db
curl http://nil.ics.uci.edu/~gal/public/bit/HEAD > .git/HEAD
http-pull -a `cat .git/HEAD` \
    http://nil.ics.uci.edu/~gal/public/bit
read-tree `cat .git/HEAD`
checkout-cache -f -a

Naturally, you can also use BIT to pull the current sources, which
is much simpler:

bit clone http://nil.ics.uci.edu/~gal/public/bit

This will create a directory "bit", pull the latest sources and perform
a check-out for you.

INSTALLATION

Put "bit" anywhere in your search path. Its only a single bash script. It
requires a link "bit-resolve" to itself and the (soft) link should reside
in the same directory as "bit" itself. "bit" acts as merge script when
invoked through that link.

At this point, BIT's functionality is minimal. It does what I need it for.
I will obviously add more commands as we go along, but I won't touch
things like tags and stuff like that until Linus' makes up his mind how to 
do it *RIGHT*.

BASIC CONCEPTS

- BIT always checks out all files in your repository and it does so
  automatically. In other words, there is no "bit co" command. Not
  everyone will like this, but I do.
- You can't seek around in a repository. Checked-out files always
  match the HEAD revision. You can diff files against older versions,
  but if you want to check out an older version, you will have to
  clone the repository (see below).
  
TRACKING SOMEONE ELSE'S TREE  
  
$ bit clone http://www.kernel.org/pub/linux/kernel/people/torvalds/git.git/

(Note: Don't forget the '/' at the end, otherwise http-pull won't work.)

This command pulls Linus' latest GIT tree to a local repository "git.git".
You can change the latter by giving clone an additional argument.
  
$ bit clone http://www.kernel.org/pub/linux/kernel/people/torvalds/git.git/ \
    git-trunk
  
Once you have a copy of the remote repository, you can check whether there
are new changesets in the remote repository that you haven't seen yet:
  
$ bit changes -R \
      http://www.kernel.org/pub/linux/kernel/people/torvalds/git.git/
      
If you see any changes, you can merge them into your own tree:
  
$ bit pull http://www.kernel.org/pub/linux/kernel/people/torvalds/git.git/
      
BRANCHING

Now lets assume you want to work on an extension to GIT. For this, we will
clone the repository:
  
$ bit clone git-trunk git-bit
  
This will create a copy of the git-trunk repository and name it "git-bit".
The object directory is shared (using a soft link), which has the nice
benefit that once you run "bit pull" on one of the repositories, the
other one will be able to merge changes without any network traffic
(except for reading the current HEAD).
  
Lets say we make some changes to sha1_file.c and want to commit it to
our local repository "git-bit":
  
... edit sha1_file.c ...
  
In case we already forgot what file we edited, "bit pending" will tells us:
  
$ bit pending
sha1_file.c
  
Just in case we still can remember what we changed, there is "bit diffs",
which shows a diff to the current HEAD or any other version of our 
tree.
  
$ bit diffs
--- 28ad1598e54200ca8ee1261ed7beb4e31e20b2f1/sha1_file.c
+++ sha1_file.c
@@ -70,6 +70,7 @@
        int i;
        static char *name, *base;
 
+       /* added a cool new feature here */
        if (!base) {
                char *sha1_file_directory = getenv(DB_ENVIRONMENT) ? : ...
                int len = strlen(sha1_file_directory);
  
To commit our changes, we use "bit commit". It will fire up "vi" to ask for
a commit message.

$ bit commit
... enter commit message in vi ...

MERGING

Lets assume Linus' put out a new version of GIT, so we want to update both of
our repositories. First lets do this for "git-trunk".

$ cd bit-trunk
$ bit pull http://www.kernel.org/pub/linux/kernel/people/torvalds/git.git/

(Note: You have to specify the URL explicitly every time because there is no
 consensus yet where to store this information. Once thats sorted out, this
 will be automatic, of course.)
 
As this repository only tracks Linus' sources, there should be no conflicts.

Now lets go to our "git-bit" repository and do the same there:

$ cd git-bit
$ bit pull http://www.kernel.org/pub/linux/kernel/people/torvalds/git.git/

Because both repositories share the object directory, you will get away
with minimal network traffic. Conflicts are resolved using RCS merge. If
that fails, you have to edit the offending files yourself.

PUSHING PATCHES UPSTREAM

Lets assume we want to send our improvements to Linus. For this, we can
ask changes to show us all local changes in our repository:

$ bit changes -L \
      http://www.kernel.org/pub/linux/kernel/people/torvalds/git.git/
      
There is currently no mechanism in BIT to generate patches automatically,
but I will add one shortly. What is working already is that you can
push your repository to a remote location:

$ bit push ssh://gal@sam.ics.uci.edu/.nfs/public_html/public/git/

This will update the remote repository via SSH and set HEAD to point
to your latest version. Please note that you have to create a 
repository at the remote location using "init-db".

HELP

Try "bit --help" to get some simple instructions how to use BIT. All
commands have builtin help as well. Try "bit commit --help". Not all
options are always implemented. Feel free to send me a patch.
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Received on Mon Apr 25 16:25:10 2005

This archive was generated by hypermail 2.1.8 : 2005-04-25 16:25:10 EST