{"thread":{"id":"1230","subject":"Patch to make README more newbie-friendly","startedAt":"2005-07-14T04:58:51Z","lastAt":"2005-07-14T16:01:01Z","messageCount":2,"participants":["Jerry Seutter","Matthias Urlichs"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"6112","messageId":"42D5F10B.5050708@pason.com","threadId":"1230","inReplyTo":null,"subject":"Patch to make README more newbie-friendly","fromName":"Jerry Seutter","fromEmail":"jerry.seutter@pason.com","sentAt":"2005-07-14T04:58:51Z","receivedAt":"2005-07-14T04:58:51Z","isPatch":false,"sender":{"key":"jerry.seutter@pason.com","avatar":null},"body":"Hi,\n\nAttached to this email is a patch that expands the README file a bit, \nincluding info about basic Cogito commands at the beginning of the file. \n  I also added an distributed VCS paragraph at the beginning for people \nlike me who are typically stuck in CVS-land.\n\nComments/critiques/flames welcome.\n\nI'd also like to include stuff about branches, but I haven't gotten my \nhead wrapped around how they work yet.  cg-branch-add expects a location\nafter the branch name and I'm not sure what to give it.  I have a test \nproject containing hello_world.py and was trying to get 2 branches going \nand be able to switch between them.  What do you use for a location in \nthis case?  I tried using \".\", but switching between branches didn't \nseem to have any affect.\n\nOn another note, I thought I heard that man pages are desired.  Is the a \ncertain group of commands I should start with?  Do you want dirt simple \nman pages, or are you looking for some <insert-buzzword-here> formatted \nsource docs?\n\nJerry\n\n\ndiff --git a/README b/README\n--- a/README\n+++ b/README\n@@ -1,12 +1,24 @@\n \tCogito and GIT: Quick Introduction\n \t~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n \n-This document describes the Cogito VCS as well as GIT.  The GIT itself is\n-merely an extremely fast and flexible filesystem-based database designed to\n-store directory trees with regard to their history.  The top layer is a\n-SCM-like tool Cogito which enables human beings to work with the database in a\n-manner to a degree similar to other SCM tools (like CVS, BitKeeper or\n-Monotone).\n+This document describes the Cogito VCS as well as GIT.  The GIT itself\n+is merely an extremely fast and flexible filesystem-based database\n+designed to store directory trees with regard to their history.  The\n+top layer is a SCM-like tool Cogito which enables human beings to work\n+with the database in a manner to a degree similar to other SCM tools\n+(like CVS, BitKeeper or Monotone).  Mere Human Beings will seldom use\n+the GIT tools directly, but use the Cogito tools instead.\n+\n+If you've only used a centralized version control system like CVS\n+before, this package may require a change in how you visualize source\n+code management.  With Cogito/GIT, every directory with a checked out\n+project is also a repository for that project.  When you commit your\n+changes, you are committing them into the repository in the current\n+directory, not to the main repository.  In order to have your changes\n+show up in the main repository they need to be merged in by a person\n+that manages that repository.  This can either be done by mailing them\n+a patch containing your changes or by giving them access to your \n+repository and having them pull in your changes.\n \n \n \tThe Cogito Version Control System\n@@ -30,8 +42,11 @@ Cogito can be obtained as a tarball from\n \n \thttp://www.kernel.org/pub/software/scm/cogito/\n \n-Download and unpack the latest version, build with make, put the executables\n-somewhere in your $PATH (or add your Cogito directory itself to your $PATH),\n+Download and unpack the latest version, build with \n+\n+        $ make\n+        $ sudo make install\n+\n and you're ready to go!\n \n The following tools are required by Cogito:\n@@ -43,7 +58,9 @@ The following tools are required by Cogi\n \n The following tools are optional but strongly recommended:\n \n-\tlibcrypto (OpenSSL)\n+\tlibcrypto (OpenSSL) (Cogito also contains an OpenSSL implementation\n+        from the Mozilla project.  To use it instead of OpenSSL, build\n+        with \"make MOZILLA_SHA1=1\"\n \trsync\n \n \n@@ -67,6 +84,46 @@ That's it! You're now in your own GIT re\n directory. Go into it and look around, but don't change anything in there.\n That's what Cogito commands are for.\n \n+Files that you want to add to the repository can be added with\n+\n+    $ cg-add newfile1 newfile2 ...\n+\n+When you do some local changes, you can do\n+\n+\t$ cg-diff\n+\n+to display them.  You can also just show which files have changed by\n+\n+    $ cg-status\n+\n+Once you have decided that you want to commit your changes, use the\n+\n+    $ cg-commit\n+\n+command, which will present you with the editor of your choice for composing\n+the commit message.\n+\n+If you want to see the changes made to the repository by a certain commit,\n+the first thing you need to know is the commit names.  A commit name in\n+Cogito/Git is the hash of the commit.  The commit history of the repository\n+is displayed with\n+\n+    $ cg-log\n+\n+Once you know the name of the commit you want to see, use\n+\n+    $ cg-diff -r FROM_COMMIT_ID[:TO_COMMIT_ID]\n+\n+To tag the repository, use cg-tag.  cg-tag defaults to tagging HEAD, but\n+you can also give it the name of a commit to tag\n+\n+    $ cg-tag TAG_NAME [COMMIT_ID]\n+\n+To display the tags you have in your repository, use\n+\n+    $ cg-tag-ls\n+\n+\n \tTurning an Existing Directory Into a Repository\n \n If you have a directory full of files, you can easily turn this into a\n@@ -198,24 +255,6 @@ the command\n repository). Then you can specify the name to cg-update and cg-pull, or use\n it anywhere where you could use the \"origin\" name.\n \n-When you do some local changes, you can do\n-\n-\t$ cg-diff\n-\n-to display them.  Of course you will want to commit. If you added any new\n-files, do\n-\n-\t$ cg-add newfile1 newfile2 ...\n-\n-first. Then examine your changes by cg-diff or just show what files did you\n-change by\n-\n-\t$ cg-status\n-\n-and feel free to commit by the\n-\n-\t$ cg-commit\n-\n command, which will present you with the editor of your choice for composing\n the commit message.\n \n@@ -247,6 +286,9 @@ or, for the same information, try this:\n \tThe \"core GIT\"\n \t~~~~~~~~~~~~~~\n \n+Note that if all you care about is committing some small bits of code\n+to a repository, you can stop reading now.\n+\n \tGIT - the stupid content tracker\n \n \"git\" can mean anything, depending on your mood.\n"},{"id":"6135","messageId":"pan.2005.07.14.16.00.53.434018@smurf.noris.de","threadId":"1230","inReplyTo":"42D5F10B.5050708@pason.com","subject":"Re: Patch to make README more newbie-friendly","fromName":"Matthias Urlichs","fromEmail":"smurf@smurf.noris.de","sentAt":"2005-07-14T16:01:01Z","receivedAt":"2005-07-14T16:01:01Z","isPatch":false,"sender":{"key":"matthias@urlichs.de","avatar":"https://gravatar.com/avatar/2708905af227313eba6f2b2ae0f7d0259b5ac5d71baef58fe5a13c699ce0bbf0?d=mp&s=160"},"body":"Hi, Jerry Seutter wrote:\n\n> I'd also like to include stuff about branches, but I haven't gotten my \n> head wrapped around how they work yet.  cg-branch-add expects a location\n> after the branch name and I'm not sure what to give it.\n\nCogito branch creation is based on the idea that you have a different\narchive _somewhere_else_ that you pull from, so it wants to store the\nsource URL in .git/branches/<name>.\n\nGit doesn't have that assumption; \"git checkout -b <name>\" simply\ncreates a new branch and switches to it. However, the git branch idea came\nsomewhat later, so there's a bit of a mismatch at the moment.\n\nSimply switching branches isn't supposed to have any effect unless you\nactually have changes in different branches. I tend to work along these\nlines:\n\n#!/bin/sh\n\ncd /tmp\nrm -rf test.$$\nmkdir test.$$\ncd test.$$\ngit-init-db\necho not-quite-empty >testfile\ncg-add testfile\necho Created test | cg-commit\ngit checkout -b one\necho foo >>testfile\necho added foo to testfile | cg-commit\ngit checkout -b two master\necho bar >> testfile\necho added bar to testfile | cg-commit\ncg-diff -r one:two | cat\ngit checkout master\ncg-merge one\ncg-merge two\n\nThe first merge fast-forwards your master tree to \"one\"; the second \ncreates a conflict (lines were added at the same location) which you'll\nhave to resolve (edit the file).\n\nvi testfile\necho Merged one and two | cg-commit\ngitk\n\n-- \nMatthias Urlichs   |   {M:U} IT Design @ m-u-it.de   |  smurf@smurf.noris.de\nDisclaimer: The quote was selected randomly. Really. | http://smurf.noris.de\n - -\nApollo, the God of light, of reason, of proportion, harmony, number --\nApollo blinds those who press too close in worship. Don't look straight\nat the sun. Go into a dark bar and have a beer with Dionysos, every now\nand then. -- Ursula K. LeGuin\n"}]}