From dd7961bc443c732d0bbdd6bda47d6c2cfda5b290 Mon Sep 17 00:00:00 2001 From: James Moger Date: Tue, 17 May 2011 22:06:07 -0400 Subject: Building site content and documentation from Markdown. --- docs/00_overview.mkd | 87 ++++++++++++++++++++++++++++++++++++++++++++++ docs/01_configuration.mkd | 73 ++++++++++++++++++++++++++++++++++++++ docs/01_eclipse.mkd | 5 +++ docs/01_faq.mkd | 1 + docs/01_releases.mkd | 1 + docs/01_screenshots.mkd | 3 ++ docs/architecture.odg | Bin 0 -> 13340 bytes docs/architecture.png | Bin 0 -> 16892 bytes docs/page_footer.html | 6 ++++ docs/page_header.html | 17 +++++++++ 10 files changed, 193 insertions(+) create mode 100644 docs/00_overview.mkd create mode 100644 docs/01_configuration.mkd create mode 100644 docs/01_eclipse.mkd create mode 100644 docs/01_faq.mkd create mode 100644 docs/01_releases.mkd create mode 100644 docs/01_screenshots.mkd create mode 100644 docs/architecture.odg create mode 100644 docs/architecture.png create mode 100644 docs/page_footer.html create mode 100644 docs/page_header.html (limited to 'docs') diff --git a/docs/00_overview.mkd b/docs/00_overview.mkd new file mode 100644 index 00000000..63898f6c --- /dev/null +++ b/docs/00_overview.mkd @@ -0,0 +1,87 @@ +## Overview +Git:Blit is an open-source, integrated pure-Java stack for managing, viewing, and serving [Git](http://git-scm.com) repositories. +Its designed primarily as a tool for small workgroups who want to host Git repositories on a Windows machine. + +Of course, since its pure-Java it should run with any JVM on any platform, but there are already [many compelling Git solutions](https://git.wiki.kernel.org/index.php/InterfacesFrontendsAndTools) for non-Windows environments. + +### Current Version + +[{0}](http://gitblit.com/{1}) based on [{2}](http://eclipse.org/jgit)   (*{3}*) + +### Features +- Out-of-the-box integrated stack requiring minimal configuration +- JGit SmartHTTP Servlet +- Web and Git Servlet authentication +- Four repository access control configurations + - *Anonymous View, Clone & Push* + - *Authenticated Push* + - *Authenticated Clone & Push* + - *Authenticated View, Clone & Push* +- Gitweb inspired UI (mostly plain html) +- Repository administration through web UI +- User administration through web UI +- Automatically generates a self-signed certificate for https communications +- Dates can optionally be displayed using browser's reported timezone +- Author and Committer email address display can be controlled +- Syntax highlighting +- Customizable regular expression handling for commit messages +- Simple repository stats +- Simple text file for server configuration +- Simple text file for users configuration +- Optional integrated Ticgit +- Optional integrated Markdown + +### Limitations +- HTTP/HTTPS are the only supported protocols +- Access controls are not path-based, they are repository-based +- Only admin users can create repositories +- Git:Blit is a full-stack solution, its not just a webapp so at this time there is no WAR build + +### Todo List +- Review spots where Git:Blit can cache data instead of abusing the disk +- Ticgit activity/timeline +- Ticgit query feature with paging support +- Ticgit ticket change history +- Implement Markdown editing +- View images on Blob page +- View other binary files Blob page + +### License +TBD + +### Architecture + +![block diagram](architecture.png "Git Blit Architecture") + +### Bundled Dependencies +The following dependencies are bundled with the Git:Blit zip file. + +- [google-code-prettify](http://code.google.com/p/google-code-prettify) +- [JavaService](http://forge.ow2.org/projects/javaservice) +- icons courtesy of [FatCow Hosting](http://www.fatcow.com/free-icons) + +### Downloaded Dependencies +The following dependencies are automatically downloaded from the Apache Maven repository and from the Eclipse Maven repository when Git:Blit is launched for the first time. + +- [JGit](http://eclipse.org/jgit) +- [Wicket](http://wicket.apache.org) +- [WicketStuff GoogleCharts](https://github.com/wicketstuff/core/wiki/GoogleCharts) +- [MarkdownPapers](http://markdown.tautua.org) +- [Jetty](http://eclipse.org/jetty) +- [SLF4J](http://www.slf4j.org) +- [Log4j](http://logging.apache.org/log4j) +- [JCommander](http://jcommander.org) +- [BouncyCastle](http://www.bouncycastle.org) + +### Building +Eclipse is recommended for development as the project settings are preconfigured. + +1. Clone the git repository from here. +2. Import the gitblit project into your Eclipse workspace.
+*There will be lots of build errors.* +3. Using Ant, execute the `build.xml` script in the project root.
+*This will download all necessary build dependencies and will also generate the Keys class for accessing settings.* +4. Select your gitblit project root and **Refresh** the project, this should correct all build problems. +5. Review the settings in `gitblit.properties` in your project root.
+Make sure you set an appropriate value for *git.repositoriesFolder*. +6. Execute the *com.gitblit.Launcher* class to start Git:Blit. \ No newline at end of file diff --git a/docs/01_configuration.mkd b/docs/01_configuration.mkd new file mode 100644 index 00000000..9e8a9f06 --- /dev/null +++ b/docs/01_configuration.mkd @@ -0,0 +1,73 @@ +## Setup and Configuration + +1. Download and unzip Git:Blit.
+*Its best to eliminate spaces in the path name as that can cause troubleshooting headaches.* +2. The server itself is configured through a simple text file.
+Open `gitblit.properties` in your favorite text editor and make sure to review and set: + - *git.repositoryFolder* + - *server.tempFolder* + - *server.httpBindInterface* and *server.httpsBindInterface* + - *server.storePassword*
+**NOTE:**
+Its recommended to use **https** wherever possible instead of http because passwords are transmitted as clear text! +3. Execute `gitblit.cmd` or `java -jar gitblit.jar` from a command-line +4. Wait a minute or two while all dependencies are downloaded and your self-signed certificate is generated. +5. Open your browser to or depending on your chosen configuration. +6. Click the *Login* link and enter the default administrator credentials: **admin / admin**
+**NOTE:**
+Make sure to change the administrator username and/or password!! + +### Administering Repositories +Repositories can be created, edited, and deleted through the web UI. They may also be created, edited, and deleted from the command-line using real Git or your favorite file manager and text editor. + +All repository settings are stored within the repository `.git/config` file under the *gitblit* section. + + [gitblit] + description = master repository + owner = Joe Owner + useTickets = false + useDocs = true + showRemoteBranches = false + accessRestriction = clone + +#### Repository Names +Repository names must be unique and are case-insensitive. The name must be composed of letters, digits, or `/ _ - .`
+Whitespace is illegal. + +### Administering Users +In contrast, all users are stored in the `users.properties` file or in the file your specified in `gitblit.properties`.
+The format of `users.properties` follows Jetty's convention for HashRealms: + + username,password,role1,role2,role3... + +#### Usernames +Usernames must be unique and are case-insensitive.
+Whitespace is illegal. + +#### Passwords +User passwords are CASE-SENSITIVE and may be *plain*, *md5*, or *crypt* formatted (see `gitblit.properties` -> *realm.passwordStorage*). + +#### User Roles +There is only one actual *role* in Git:Blit and that is *#admin* which grants administrative powers to that user. Administrators automatically have access to all repositories. All other *roles* are actually repository names. If a repository is access-restricted, the user must have the repository's name within his/her roles to bypass the access restriction. This is how users are granted access to a restricted repository. + +### Creating your own Self-Signed Certificate + +Review the contents of the `makekeystore.cmd` or `makekeystore_jdk.cmd`script and execute it. Voila. + +### Running as a Service +Review the contents of the `installService.cmd` or `installService64.cmd`, as appropriate for your JVM.
+Set the *JDK* variable in the script to the location of your JDK, add any necessary start parameters, and execute the script. + +#### Command-Line Parameters + --tempFolder Server temp folder + --repositoriesFolder Git Repositories Folder + --realmFile Users Realm Hash File + --useNio Use NIO Connector else use Socket Connector. + --httpPort HTTP port for to serve. (port <= 0 will disable this connector) + --httpsPort HTTPS port to serve. (port <= 0 will disable this connector) + --storePassword Password for SSL (https) keystore. + --shutdownPort Port for Shutdown Monitor to listen on. (port <= 0 will disable this monitor) + +**Example** + + java -jar gitblit.jar --realmFile c:\myrealm.txt --storePassword something \ No newline at end of file diff --git a/docs/01_eclipse.mkd b/docs/01_eclipse.mkd new file mode 100644 index 00000000..93fd5315 --- /dev/null +++ b/docs/01_eclipse.mkd @@ -0,0 +1,5 @@ +## Eclipse Tips + +verifySsl + +how to push new unshared project to new repository \ No newline at end of file diff --git a/docs/01_faq.mkd b/docs/01_faq.mkd new file mode 100644 index 00000000..c92bfabd --- /dev/null +++ b/docs/01_faq.mkd @@ -0,0 +1 @@ +## Frequently Asked Questions diff --git a/docs/01_releases.mkd b/docs/01_releases.mkd new file mode 100644 index 00000000..7c0c2040 --- /dev/null +++ b/docs/01_releases.mkd @@ -0,0 +1 @@ +## Release History diff --git a/docs/01_screenshots.mkd b/docs/01_screenshots.mkd new file mode 100644 index 00000000..666e943f --- /dev/null +++ b/docs/01_screenshots.mkd @@ -0,0 +1,3 @@ +## Screenshots + +![test](gitblt_25.png "Optional Title") \ No newline at end of file diff --git a/docs/architecture.odg b/docs/architecture.odg new file mode 100644 index 00000000..fc4ea7b7 Binary files /dev/null and b/docs/architecture.odg differ diff --git a/docs/architecture.png b/docs/architecture.png new file mode 100644 index 00000000..d2f3e0c7 Binary files /dev/null and b/docs/architecture.png differ diff --git a/docs/page_footer.html b/docs/page_footer.html new file mode 100644 index 00000000..80b14d0c --- /dev/null +++ b/docs/page_footer.html @@ -0,0 +1,6 @@ + +
+
{0}
+
+ + \ No newline at end of file diff --git a/docs/page_header.html b/docs/page_header.html new file mode 100644 index 00000000..d282f54d --- /dev/null +++ b/docs/page_header.html @@ -0,0 +1,17 @@ + + + Git:Blit + + + + + + +
+ + + + {0} +
+
{1}
+
\ No newline at end of file -- cgit v1.2.3