README.rdoc in gitolite-0.0.2.alpha vs README.rdoc in gitolite-0.0.3.alpha

- old
+ new

@@ -5,13 +5,17 @@ This gem is still under very active development. There are a number of issues with it still. It is not ready for production use. == Features * Allows for the creation and management of repos within gitolite * Allows for the creation and deletion of SSH keys within gitolite +* Allows for the bootstrapping of a gitolite-admin repository +== Issues +* Gem is not thread safe. For now, the gem will change directories in order to perform git operations. It will, however, return to the old working directory once it is finished. I am looking into making the gem thread safe. + == Requirements -* Ruby 1.9.2 or higher +* Ruby 1.8.x or 1.9.x * a working {gitolite}[https://github.com/sitaramc/gitolite] installation * the <tt>gitolite-admin</tt> repository checked out locally == Installation @@ -21,60 +25,120 @@ === Load a gitolite-admin repo require 'gitolite' ga_repo = Gitolite::GitoliteAdmin.new("/path/to/gitolite/admin/repo") - -For now, this method can only be called on an existing gitolite-admin repo. Support for bootstrapping a gitolite-repo will be added in the future (but will never be recommended). - + +This method can only be called on an existing gitolite-admin repo. If you need to create a new gitolite-admin repo, see "Bootstrapping". + +=== Configuration Files + + conf = ga_repo.config + + #Empty configs can also be initialized + conf2 = Config.init # => defaults to a filename of gitolite.conf + conf2 = Config.init("new_config.conf") + + #Filename is set to whatever the filename was when the config was created + conf.filename # => "gitolite.conf" + conf2.filename # => "new_config.conf") + + #filename can be changed via the setter + conf2.filename = "new_config.conf" + + #to_file will write the config out to the file system + #using the value of the filename attribute. An alternative + #filename can also be specified + conf.to_file("/new/config/path") # => writes /new/config/path/gitolite.conf + conf.to_file("/new/config/path", "test.conf") # => writes /new/config/path/test.conf + === Repo management - repo = Config::Repo.new("AwesomeRepo") - + repo = Gitolite::Config::Repo.new("AwesomeRepo") + #For a list of permissions, see https://github.com/sitaramc/gitolite/blob/pu/doc/gitolite.conf.mkd repo.add_permission("RW+", "", "bob", "joe", "susan") - - #Add repo - ga_repo.add_repo(repo) - - #Delete repo - ga_repo.rm_repo(repo) + #Add repo to config + conf.add_repo(repo) + + #Delete repo by object + conf.rm_repo(repo) + + #Delete a repo by name + conf.rm_repo("AwesomeRepo") + conf.rm_repo(:AwesomeRepo) + + #Test if repo exists by name + conf.has_repo?('cool_repo') # => false + conf.has_repo?(:cool_repo) # => false + + #Can also pass a Gitolite::Config::Repo object + repo = Gitolite::Config::Repo.new('cool_repo') + conf.has_repo?(repo) # => true + + #Get a repo object from the config + repo = conf.get_repo('cool_repo') + repo = conf.get_repo(:cool_repo) + === SSH Key Management #Two ways to create keys: manually or from an existing key key = Gitolite::SSHKey.new("ssh-rsa", "big-public-key-blob", "email") key2 = Gitolite::SSHKey.from_file("/path/to/ssh/key.pub") - + #Add the keys ga_repo.add_key(key) ga_repo.add_key(key2) #Remove key2 ga_repo.rm_key(key2) === Save changes ga_repo.save - + When this method is called, all changes get written to the file system and staged in git. For the time being, gitolite assumes full control of the gitolite-admin repository. This means that any keys in the keydir that are not being tracked will be removed and any human changes to gitolite.conf will be erased. === Apply changes ga_repo.apply This method will commit all changes with a generic message (will be improved upon later) and push to <tt>origin master</tt>. - + === Save and apply ga_repo.save_and_apply +=== Bootstrapping + ga_repo = GitoliteAdmin.bootstrap("/path/to/new/gitolite/repo") + +This will create the folders <tt>conf</tt> and <tt>keydir</tt> in the supplied path. A config file will also be created in the conf directory. The default configuration supplies RW+ permissions to a user named git for a repo named <tt>gitolite-admin</tt>. You can specify an options hash to change some values: + + ga_repo = GitoliteAdmin.bootstrap("/path/to/new/gitolite/repo", {:user => "admin", :perm => "RW"}) + +You can also pass a message to be used for the initial bootstrap commit: + + ga_repo = GitoliteAdmin.bootstrap("/path/to/new/gitolite/repo", {:message => "Bootstrapped new repo"}) + +Please note that while bootstrapping is supported, I highly recommend that the initial gitolite-admin repo be created by gitolite itself. + == Caveats -=== 1.8.x compatibility -This gem should work properly on Ruby 1.8.x with the exception of deny rules. In order to fully support Ruby < 1.9.x, an ordered Hash is required. The one implemented by ActiveSupport could probably be used. Support will be added if there appears to be a demand for it. +=== Windows compatibility +The grit gem (which is used for under-the-hood git operations) does not currently support Windows. Until it does, gitolite will be unable to support Windows. +== Contributing +* Tests! If you ask me to pull changes that are not adequately tested, I'm not going to do it. +* If you introduce new features/public methods on objects, you must update the README. + +=== Contributors +* Alexander Simonov - {simonoff}[https://github.com/simonoff] + == Documentation * Rdoc is coming soon == Future * support folders in the keydir -* support includes tags -* support bootstrapping a gitolite-admin repo -* cleanup methods to make adding and removing easier (like add_key should accept an array of keys) \ No newline at end of file +* support include tags +* support pull operations to sync the local gitolite-admin repository with the server +* cleanup methods to make adding and removing easier (like add_key should accept an array of keys) +* Rails integration +* Make the gem thread safe +* Add full support for Wildcard repos