{"id":15792819,"url":"https://github.com/mikeralphson/cogito","last_synced_at":"2026-05-19T10:06:16.470Z","repository":{"id":66094078,"uuid":"157921788","full_name":"MikeRalphson/cogito","owner":"MikeRalphson","description":"Git Interface for Humans","archived":false,"fork":false,"pushed_at":"2018-11-16T21:12:12.000Z","size":2470,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-11T23:18:20.557Z","etag":null,"topics":["cogito","dvcs","git","git-toolkit","scm"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MikeRalphson.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-16T21:11:53.000Z","updated_at":"2024-07-05T03:05:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"541ac9a0-7f5b-4191-a472-4a34b1456cbb","html_url":"https://github.com/MikeRalphson/cogito","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeRalphson%2Fcogito","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeRalphson%2Fcogito/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeRalphson%2Fcogito/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeRalphson%2Fcogito/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MikeRalphson","download_url":"https://codeload.github.com/MikeRalphson/cogito/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246523897,"owners_count":20791444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cogito","dvcs","git","git-toolkit","scm"],"created_at":"2024-10-04T23:04:53.398Z","updated_at":"2026-05-19T10:06:16.444Z","avatar_url":"https://github.com/MikeRalphson.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"The Cogito Version Control System\n=================================\n\nCogito is a version control system layered on top of the git tree history\nstorage system. It aims at seamless user interface and ease of use, providing\ngenerally smoother user experience than the \"raw\" Core GIT itself and indeed\nmany other version control systems.\n\nWe shall first describe some quick ways to get started using Cogito, then go\nover each available command one by one.\n\nPlease note that this document (meant to serve as a kind of Cogito tutorial\nin the future) is quite sketchy so far; a much better starting tutorial might\nbe one of the Git Crash Courses featured at the Git homepage\n(http://git.or.cz/). The reference documentation should be of pretty good\nquality (see the 'Getting help' section at the bottom of this file).\n\nYou can find the Cogito homepage at http://git.or.cz/cogito/[].\n\n\nCogito is quite easy and intuitive to use. If you want to dive right in,\nsee cg-ref(7) for a quick commands/concepts reference and cg-help(1)\nor cogito(7) for a reference manual.\n\n\n\nInstalling\n----------\n\nIf your distribution does not offer Cogito by itself, Cogito can be obtained as\na tarball from\n\n - http://www.kernel.org/pub/software/scm/cogito/[]\n\nDownload and unpack the latest version, build with make, put the executables\nsomewhere in your `$PATH` (or add your Cogito directory itself to your `$PATH`),\nand you're ready to go!\n\nThe following tools are vitally required by Cogito to do anything useful:\n\n`-------------------------------`----------------------------------------------\nTool\t\t\t\tDescription\n-------------------------------------------------------------------------------\ngit-core\t\t\tCogito is just a frontend for git.\nbash\t\t\t\tAll Cogito executables are scripted in bash.\nsed, grep, textutils, etc.\tThe basic shell environment.\ndiff, patch\t\t\tThe basic utilities for tracking file changes.\n-------------------------------------------------------------------------------\n\nThe following tools are very recommended for regular Cogito operation:\n\n`-------------------------------`----------------------------------------------\nTool\t\t\t\tDescription\n-------------------------------------------------------------------------------\ncurl\t\t\t\tFor fetching files with the HTTP backend.\nssh\t\t\t\tFor fetching files with the git+ssh backend.\n-------------------------------------------------------------------------------\n\nThe following tools are optional but recommended:\n\n`-------------------------------`----------------------------------------------\nTool\t\t\t\tDescription\n-------------------------------------------------------------------------------\nrsync\t\t\t\tFor fetching files with the rsync backend.\nGNU coreutils\t\t\tThe GNU versions of stat, date and cp \\\n\t\t\t\tare preferred over the BSD variants.\nasciidoc (\u003e= 7.0), xmlto\tFor building documentation.\n-------------------------------------------------------------------------------\n\n\n\nGetting started\n---------------\n\nStarting a Fresh GIT Repository\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIf you want to start your own project using Cogito, there are two basic ways\nto do this. You may start a fresh repository with no files in it, or you may\ntake an existing directory tree and turn it into a GIT repository.\n\nStarting an Empty Repository\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nTo create a new repository with no files in it, `cd` into an empty directory,\nand give the following command:\n\n\t$ cg-init\n\nYour editor will start up, and you will be asked to type in the initial\ncommit description. Type something cute, and exit your editor.\n\nThat's it! You're now in your own GIT repository. Notice there is now a `.git`\ndirectory. Go into it and look around, but don't change anything in there.\nThat's what Cogito commands are for.\n\nTurning an Existing Directory Into a Repository\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nIf you have a directory full of files, you can easily turn this into a\nGIT repository. In fact, it is virtually the same as starting an empty\nrepository. Just `cd` into the directory you want converted into a GIT\nrepository, and give the following command:\n\n\t$ cg-init\n\nYour editor starts up, you type in an initial commit message, exit your\neditor, and you're good to go. All of the files and directories within that\ndirectory are now part of a GIT archive.\n\n\nAccessing Someone Else's GIT Repository\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nCloning the Repository\n^^^^^^^^^^^^^^^^^^^^^^\n\nIf you want to get started tracking an outside GIT repository, you first\nmust have Cogito's executables on your `$PATH`. Next, you need the URL (or\nlocal directory path) of the repository you want to track. You can't just\nuse the URL of a tarball, like the one given above for the Cogito source.\nThe URL must point specifically to a `.git` directory somewhere. For instance,\nthe URL for Cogito's self-hosting repository is\n\n\thttp://www.kernel.org/pub/scm/cogito/cogito.git\n\nNotice that the final directory, `cogito.git`, is not called `.git`. That is\nfine. It still has the same content as your `.git` directory.\n\nTo clone the repository to your local filesystem, use the cg-clone command.\ncg-clone can be told to create a new directory for your repository, or to\ndrop the repository into the current directory.\n\nTo have a new directory created, just invoke cg-clone with the URL.  You can\nalso include the directory in the command to specify exactly how should the\nnew directory be called, as follows:\n\n\t$ cg-clone http://www.kernel.org/pub/scm/cogito/cogito.git cogitodir\n\nYou will watch a progressbar for a while and when it is over there will be a\nnew directory called 'cogitodir' (or whatever name you chose) in the current\ndirectory. `cd` into it. Because we used the Cogito URL, you will see the\nCogito source tree, with its own `.git` directory keeping track of everything.\n\nNote that the 'cogitodir' argument is optional; if you don't specify it,\ncg-clone will automatically determine the directory name from the URL - it\nwould be 'cogito' for the URL we used. (Note that it's safe as cg-clone will\nrefuse to do anything if the directory already exists.)\n\nIf, instead, you want to clone the repository to the current directory,\nfirst make sure you are in an empty directory. Then give the following\ncommand:\n\n\t$ cg-clone -s http://www.kernel.org/pub/scm/cogito/cogito.git\n\nWhen you get your prompt back, do an ls to see the source tree and `.git`\ndirectory.\n\nTracking Others' Work\n^^^^^^^^^^^^^^^^^^^^^\n\nOf course, once you have cloned a repository, you don't just want to leave\nit at that. The upstream sources are constantly being updated, and you want\nto follow these updates. To do this, `cd` into the working tree directory (not\nthe `.git` directory, but the directory that contains the `.git` directory), and\ngive the following command:\n\n\t$ cg-update\n\nYou don't use a URL anymore - Cogito knows which tree you're tracking, because\nthis information is stored in the `.git` directory. The above command will track\nthe 'origin' branch, which represents the repository you originally cloned.\nBut cg-update can be also used to track specific branches. See below for more\ndiscussion of branches and how to track them.\n\nWhen you give the above `cg-update` command, this performed two actions.\nFirst, it fetched all new changes from the upstream repository into your\nlocal repository. At that point, the changes exist in your local repository\nas part of the project history. The changes themselves are not actually\nvisible in the files you see, but reside in the `.git` directory's awareness,\njust downloaded and ready to be merged somewhere.  The second thing `cg-update`\ndoes is to merge these changes into the files you see and work with. The end\nresult is that when the `cg-update` has finished, you will see all the\nupstream changes reflected in your local files, and the `.git` directory will\nbe aware of the history of those changes as well.\n\nIt may be that you want to be aware of the history of the upstream work, but\nyou don't yet want those changes merged with your own local files. To do\nthis, give the following command:\n\n\t$ cg-fetch\n\nThis does the first part of cg-update's job, but skips the second part.\nNow your local files have not been changed, but your `.git` directory has been\nupdated with the history of all the changes that have occurred in the\nupstream sources.\n\nUsing `cg-fetch` is useful for a variety of purposes, for instance if you want\nto construct a diff against the latest version of the upstream sources, but\ndon't want those changes to disturb your ongoing work. `cg-fetch` will update\nyour `.git` directory with the history you need to construct your diff,\nwithout merging that history into your tree, potentially breaking your\nchanges.\n\nTypically, if you are not making changes to the project yourself, but just\nwant the latest version of a given project for your own use, you would use\n`cg-update`. `cg-fetch` is strictly for development work.\n\nOnce you've done a `cg-fetch`, you may decide you want to merge after all. In\nthis case a `cg-update` command will do the trick, however you will also\nupdate your local files with any further upstream changes that have occurred\nsince your `cg-fetch`. The alternative and more powerful way is using\nthe `cg-merge` command, which we shall describe later.\n\n\n\nUsing Cogito\n------------\n\nIf there are any changes, two IDs will be printed during `cg-fetch` or\n`cg-update` run (I mean the line saying \"Tree change\"). Pass those as\nparameters to cg-diff and you will get a diff describing changes from\nthe last time you fetched. You can also\n\n\t$ cg-diff -r origin..HEAD\n\nwhich will show changes between the cloned branch and your current branch\n(shall you do any modifications).\n\nNote that you can also access other branches than the one you cloned from,\nby adding it with the command\n\n\t$ cg-branch-add name repourl\n\n(the repourl can have a fragment part identifying a branch inside of the\nrepository). Then you can pass the 'name' to `cg-update` and `cg-fetch`\nor use it anywhere where you could use the 'origin' name.\n\nWhen you do some local changes, you can do\n\n\t$ cg-diff\n\nto display them.  Of course you will want to commit. If you added any new\nfiles, do\n\n\t$ cg-add newfile1 newfile2 ...\n\nfirst. Then examine your changes by `cg-diff` or just list what files did you\nchange by\n\n\t$ cg-status\n\nand feel free to commit by the\n\n\t$ cg-commit\n\ncommand, which will present you with the editor of your choice for composing\nthe commit message. (`cg-commit` also has a very convenient command-line\nusage.)\n\nIt is nice to be able to examine the commit history. We have tool for that too:\n\n\t$ cg-log -r origin\n\nwill get you the history of the branch you cloned from. `cg-log` with no\narguments will default to the history of the current branch. Try also\nprepending the `-c` and `-f` options. To only get a brief overview of the\nchanges, do\n\n\t$ cg-log -s\n\n\nNote that we gave only a glimpse to the basic usage, but there is a lot more\n- merging (`cg-merge`), moving your tree to an older commit (`cg-seek`),\npushing (`cg-push`), etc.\n\n\nUnderstanding Cogito branching and merging\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nCogito's (partially inherited from GIT) concept of branching and merging may be\na little confusing at first, since it can be different from what you knew so far.\nFirst, \"branch\" is too abstract word for us, so we will abandon it for now.\nWe will present two other key concepts instead:\n\n\t- Repository - when you did `cg-clone` or `cg-init`, you created\n\t  a repository. That is a kind of container holding (usually) all your\n\t  history and data.\n\n\t- Head - each repository has some heads available. Those are kind of\n\t  handles for various sequences of commit. A head contains simply a\n\t  pointer to the last commit in the sequence, and if you commit 'onto'\n\t  a head, the pointer will be advanced to the new commit. Your\n\t  \"current\" head is the one you are currently working on. It is\n\t  normally called 'master'.\n\nNow let's take an hypothetical repository:\n\n\trepository\n\t+--------+\n\t|  master\u003c  heads (denoted by the '\u003c')\n\t|   unoji\u003c\n\t+--------+\n\nLet's suppose that we want to fork off master's development. We have two\npossibilities, either make new repository for it, or a new head.\n\nLet's say that we want to fork it off for our work offline on a notebook,\nso we will make it through cloning the repository to our notebook. What\nwill `cg-clone` do?\n\n\t+--------+\n\t+--------+\n\nFirst it creates an empty repository\n\n\t+--------+\n\t$  origin\u003c\n\t+--------+\n\nThen it creates an 'origin' head, and will copy all the history from the\nremote repository's 'master' head there. So this head exists to reflect\nthe state of the remote repository. The important point is that it is\ncalled 'origin' in our new repository, even through it corresponds to\na 'master' head in the old repository. This is normal - you can name your\nlocal heads whatever you want.\n\nThe dollar sign denotes that this head is associated with a \"remote branch\"\n- a source location of the head is saved somewhere and you can fetch the\nhead and possibly push to it.\n\n\t+--------+\n\t|  master\u003c\n\t$  origin\u003c\n\t+--------+\n\nFinally it copied over the 'origin' head to the 'master' head, which will\nfrom now as your current head represent your local development in the\nrepository.\n\nSo you do some local development, do few commits on the 'master' head and\nwant to catch up with the upstream repository. You use 'cg-update', but what\nwill it do?\n\n\t+--------+\n\t|  master\u003c\n\t$  origin\u003c-F--- - - ... remote repository ...\n\t+--------+\n\nFirst, it will fetch: populate your 'origin' head with the new commits from\nthe remote's 'master' head.\n\n\t+--------+\n\t|  master\u003c-M-.\n\t$  origin\u003e---'\n\t+--------+\n\nThen, it will merge those new commits to your 'master' head.\n\nNow let's imagine that there is also another head 'unoji' on the other side\nbesides 'master', containing some cool commits not in 'master' (it has such an\nexotic name, after all...). You want to merge its commits to your head too?\n\n\t$ cg-branch-add r-unoji 'http://remote/repository#unoji'\n\t$ cg-fetch r-unoji\n\nwill make your repository look like\n\n\t+--------+\n\t|  master\u003c\n\t$  origin\u003c\n\t$ r-unoji\u003c\n\t+--------+\n\nwith 'r-unoji' containing stuff from the remote's 'unoji' branch.\n\nOk, you did some development, but you decided not to merge it into upstream's\n'master' yet since it is not yet stable enough. However, you want to upload it\ninto the upstream repository since it is public and you want people to be able\nto try out your stuff. Easy, let's push it to a new head on the server.\n\n\t$ cg-branch-add upmirror 'git+ssh://remote/repository#nislu'\n\nwill make your repository look like:\n\n\t+--------+\n\t|  master\u003c\n\t$  origin\u003c\n\t$ r-unoji\u003c\n\t$upmirror|\n\t+--------+\n\nNote that 'upmirror' has no head associated, it has just the \"remote branch\"\ninfo. That is because it needs no head since it's solely for pushing. It is\nhowever normal to have a head (frequently it's the 'origin') both for fetching\nand pushing.\n\n\t$ cg-push upmirror\n\nwill then make the remote repository look like:\n\n\t+--------+\n\t|  master\u003c\n\t|   unoji\u003c\n\t|   nislu\u003c\n\t+--------+\n\nwith 'nislu' on the remote side corresponding to the 'master' in your local\nrepository.\n\nOk, so this is how it goes for multiple repositories, where the cloned\nrepositories are essentially single branches. Note that if you clone the\nrepository locally, it can be actually very cheap, basically for free with\n`cg-clone -l` (but please read its documentation).\n\nBut what if you still do not want multiple repositories? The key here is to\nchange your \"current head\" from 'master' to some new head, and then to be\nable to switch back and forth:\n\n\t$ cg-switch -c aspyk\n\nto create a new 'aspyk' head (based on your current commit) and switch\nto it, and\n\n\t$ cg-switch master\n\nto switch back to 'master' later, etc.\n\nYou can get the list of available heads by\n\n\t$ cg-status -g\n\nwhere the current head is marked by '\u003e' and remote heads are marked by 'R'.\nYou can also get the list of source locations for remote heads by\n\n\t$ cg-branch-ls\n\n\nUsing Cogito for team work\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nA small team with SSH access to a shared server can use Cogito in a way\nsimilar to traditional CVS over SSH.\n\nIf you are bootstrapping the project, and you have a local Cogito working\ncopy, you must set up the shared repository and push a local head to it.\n\nTo set up the shared repository, for example in\n\n\tremoteserver:/srv/git/projectname.git\n\nlogin to the remote server and do:\n\n\t$ mkdir /srv/git\n\t$ cg-admin-setuprepo -g gitcommit /srv/git/projectname.git\n\nNote: All the developers with \"push\" access must then obviously belong\nto the 'gitcommit' group on the remote server.\n\nGoing back to your Cogito working copy, run:\n\n\t$ cg-branch-add origin git+ssh://remoteserver/srv/git/project.git\n\t$ cg-push\n\nNow your other team members can start working with you, doing\n\n         $ cg-clone git+ssh://remoteserver/var/git/project.git\n\nand when they are ready to push their work onto the shared repository,\nthey just do:\n\n         $ cg-update\n         $ cg-push\n\n\nCogito vs. other GIT tools\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nYou can *MOSTLY* use Cogito in parallel with other GIT frontends (e.g. StGIT),\nas well as the GIT plumbing and core GIT tools - the tools only need to keep\nHEAD in place and follow the standardized `refs/` hierarchy. The only notable\nexception is that you should stick with a single toolkit during a merge. Also,\nyou can't use `cg-update` and `cg-fetch` out of the box on repositories produced\nby `git clone` since it uses incompatible branches representation.\n\n\n\nGetting Help\n------------\n\nCogito commands come with their own documentation. To get quick usage help on\ncg-fetch, for example, give this command:\n\n\t$ cg-fetch --help\n\nor, for a command's full reference manual, you can use either of these:\n\n\t$ cg-fetch --long-help\n\t$ cg-help cg-fetch\n\nAlternatively, the man pages for the individual commands can be used as a\nreference (their content is equivalent to the cg-help output).\ncogito(7) is a good starting point.\n\nYou can ask thoughtful questions and make suggestions on the GIT mailing list:\n\n\tgit@vger.kernel.org\n\nor (less preferably) contact the maintainer Petr Baudis \u003cpasky@suse.cz\u003e\ndirectly.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeralphson%2Fcogito","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikeralphson%2Fcogito","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeralphson%2Fcogito/lists"}