Documentation and build script improvements.

James Moger

2011-07-20 230632f582e7f1647cf15bc3ebd6148cb9af43c0

Documentation and build script improvements.

 build.xml

@@ -250,9 +250,17 @@
                <arg value="--substitute" />

                <arg value="%JGIT%=${jgit.version}" />



                <arg value="--load" />

                <arg value="--properties" />

                <arg value="%PROPERTIES%=${basedir}/distrib/gitblit.properties" />



                <arg value="--nomarkdown" />

                <arg value="%BEGINCODE%:%ENDCODE%" />



                <arg value="--substitute" />

                <arg value="&quot;%BEGINCODE%=&lt;pre class='prettyprint lang-java'&gt;&quot;" />



                <arg value="--substitute" />

                <arg value="%ENDCODE%=&lt;/pre&gt;" />

            </java>

    </target>

    

@@ -383,6 +391,14 @@
            </fileset>

        </copy>



        <!-- Copy google-code-prettify -->

        <mkdir dir="${basedir}/src/com/gitblit/wicket/pages/prettify" />

        <copy todir="${project.site.dir}/prettify">

            <fileset dir="${basedir}/src/com/gitblit/wicket/pages/prettify">

                <exclude name="thumbs.db" />

            </fileset>

        </copy>



        <!-- Generate thumbnails of screenshots -->

        <java classpath="${project.build.dir}" classname="com.gitblit.build.BuildThumbnails">

            <classpath refid="master-classpath" />

@@ -449,6 +465,15 @@


            <arg value="--properties" />

            <arg value="%PROPERTIES%=${basedir}/distrib/gitblit.properties" />

			
            <arg value="--nomarkdown" />

            <arg value="%BEGINCODE%:%ENDCODE%" />



            <arg value="--substitute" />

            <arg value="&quot;%BEGINCODE%=&lt;pre class='prettyprint lang-java'&gt;&quot;" />



            <arg value="--substitute" />

            <arg value="%ENDCODE%=&lt;/pre&gt;" />



        </java>    

    </target>


 docs/00_index.mkd

@@ -23,9 +23,15 @@


**%VERSION%** ([go](http://code.google.com/p/gitblit/downloads/detail?name=%GO%)|[war](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%)) based on [%JGIT%][jgit] &nbsp; *released %BUILDDATE%*



- forward-slashes ('/', %2F) can be encoded using a custom character to workaround some servlet container default security measures for proxy servers<br/>**New:** *web.forwardSlashCharacter = /*

- optionally display repository on-disk size on repositories page<br/>**New:** *web.showRepositorySizes = true*

- tone-down repository group header color

- fixed: bare-cloned repositories were listed as (empty) and were not clickable (issue 13)

- fixed: default port for Gitblit GO is now 8443 to be more linux/os x friendly (issue 12)

- fixed: forward-slashes ('/', %2F) can be encoded using a custom character to workaround some servlet container default security measures for proxy servers<br/>**New:** *web.forwardSlashCharacter = /* (issue 11)

- fixed: users can now change their passwords (issue 1)

- fixed: always show root repository group first, i.e. don't sort root group with other groups

- fixed: tone-down repository group header color

- added: optionally display repository on-disk size on repositories page<br/>**New:** *web.showRepositorySizes = true*

- updated: MarkdownPapers 1.1.0

- updated: Jetty 7.4.4



issues & binaries @ [Google Code][googlecode]<br/>

sources @ [Github][gitbltsrc]


 docs/01_setup.mkd

@@ -20,11 +20,12 @@
Open `gitblit.properties` in your favorite text editor and make sure to review and set:

    - *git.repositoryFolder* (path may be relative or absolute)

    - *server.tempFolder* (path may be relative or absolute)

    - *server.httpPort* and *server.httpsPort*<br/>

    - *server.httpBindInterface* and *server.httpsBindInterface*<br/>

    **https** is strongly recommended because passwords are insecurely transmitted form your browser/git client using Basic authentication!     

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 *localhost* certificate is generated.<br/>Please see the section titled **Creating your own Self-Signed Certificate** to generate a certificate for *your hostname*.

5. Open your browser to <http://localhost> or <https://localhost> depending on your chosen configuration.

5. Open your browser to <http://localhost:8080> or <https://localhost:8443> depending on your chosen configuration.

6. Click the *Login* link and enter the default administrator credentials: **admin / admin**<br/>

    **NOTE:** Make sure to change the administrator username and/or password!! 



@@ -164,6 +165,138 @@


Your user service class must be on Gitblit's classpath and must have a public default constructor. 



%BEGINCODE%

public interface IUserService {



    /**

     * Does the user service support cookie authentication?

     * 
     * @return true or false

     */

    boolean supportsCookies();



    /**

     * Returns the cookie value for the specified user.

     * 
     * @param model

     * @return cookie value

     */

    char[] getCookie(UserModel model);



    /**

     * Authenticate a user based on their cookie.

     * 
     * @param cookie

     * @return a user object or null

     */

    UserModel authenticate(char[] cookie);



    /**

     * Authenticate a user based on a username and password.

     * 
     * @param username

     * @param password

     * @return a user object or null

     */

    UserModel authenticate(String username, char[] password);



    /**

     * Retrieve the user object for the specified username.

     * 
     * @param username

     * @return a user object or null

     */

    UserModel getUserModel(String username);



    /**

     * Updates/writes a complete user object.

     * 
     * @param model

     * @return true if update is successful

     */

    boolean updateUserModel(UserModel model);



    /**

     * Adds/updates a user object keyed by username. This method allows for

     * renaming a user.

     * 
     * @param username

     *            the old username

     * @param model

     *            the user object to use for username

     * @return true if update is successful

     */

    boolean updateUserModel(String username, UserModel model);



    /**

     * Deletes the user object from the user service.

     * 
     * @param model

     * @return true if successful

     */

    boolean deleteUserModel(UserModel model);



    /**

     * Delete the user object with the specified username

     * 
     * @param username

     * @return true if successful

     */

    boolean deleteUser(String username);



    /**

     * Returns the list of all users available to the login service.

     * 
     * @return list of all usernames

     */

    List<String> getAllUsernames();



    /**

     * Returns the list of all users who are allowed to bypass the access

     * restriction placed on the specified repository.

     * 
     * @param role

     *            the repository name

     * @return list of all usernames that can bypass the access restriction

     */

    List<String> getUsernamesForRepositoryRole(String role);



    /**

     * Sets the list of all uses who are allowed to bypass the access

     * restriction placed on the specified repository.

     * 
     * @param role

     *            the repository name

     * @param usernames

     * @return true if successful

     */

    boolean setUsernamesForRepositoryRole(String role, List<String> usernames);



    /**

     * Renames a repository role.

     * 
     * @param oldRole

     * @param newRole

     * @return true if successful

     */

    boolean renameRepositoryRole(String oldRole, String newRole);



    /**

     * Removes a repository role from all users.

     * 
     * @param role

     * @return true if successful

     */

    boolean deleteRepositoryRole(String role);



    /**

     * @See java.lang.Object.toString();

     * @return string representation of the login service

     */

    String toString();

}

%ENDCODE%



## Client Setup and Configuration

### Https with Self-Signed Certificates

You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations.


 docs/02_faq.mkd

@@ -37,7 +37,10 @@
Confirm that the &lt;context-param&gt; *realm.userService* value in your `web.xml` file actually points to a `users.properties` file.



### Gitblit won't open my grouped repository (/group/myrepo.git) or browse my branch/tag/ref?!

This is likely an url encoding/decoding problem.  In `gitblit.properties` or `web.xml`, try setting *web.mountParameters* to *false*.

This is likely an url encoding/decoding problem related to your servlet container's security.  There are two possible workarounds for this issue.  In `gitblit.properties` or `web.xml`:



1. try setting *web.mountParameters* to *false*.<br/>This changes the url scheme from mounted (*/commit/myrepo.git/abcdef*) to parameterized (*/commit/?r=myrepo.git&h=abcdef*).

2. try changing *web.forwardSlashCharacter* to an asterisk or a **!**



## General Interest Questions




 docs/04_releases.mkd

@@ -3,9 +3,15 @@
### Current Release

**%VERSION%** ([go](http://code.google.com/p/gitblit/downloads/detail?name=%GO%)|[war](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%)) based on [%JGIT%][jgit] &nbsp; *released %BUILDDATE%*



- forward-slashes ('/', %2F) can be encoded using a custom character to workaround some servlet container default security measures for proxy servers<br/>**New:** *web.forwardSlashCharacter = /*

- optionally display repository on-disk size on repositories page<br/>**New:** *web.showRepositorySizes = true*

- tone-down repository group header color

- fixed: bare-cloned repositories were listed as (empty) and were not clickable (issue 13)

- fixed: default port for Gitblit GO is now 8443 to be more linux/os x friendly (issue 12)

- fixed: forward-slashes ('/', %2F) can be encoded using a custom character to workaround some servlet container default security measures for proxy servers<br/>**New:** *web.forwardSlashCharacter = /* (issue 11)

- fixed: users can now change their passwords (issue 1)

- fixed: always show root repository group first, i.e. don't sort root group with other groups

- fixed: tone-down repository group header color

- added: optionally display repository on-disk size on repositories page<br/>**New:** *web.showRepositorySizes = true*

- updated: MarkdownPapers 1.1.0

- updated: Jetty 7.4.4



### Older Releases

**0.5.1** ([go](http://code.google.com/p/gitblit/downloads/detail?name=gitblit-0.5.1.zip)|[war](http://code.google.com/p/gitblit/downloads/detail?name=gitblit-0.5.1.war)) based on [JGit 1.0.0 (201106090707-r)][jgit] &nbsp; *released 2006-06-28*


 src/com/gitblit/build/BuildSite.java

@@ -17,11 +17,9 @@


import java.io.BufferedReader;

import java.io.File;

import java.io.FileInputStream;

import java.io.FileOutputStream;

import java.io.FileReader;

import java.io.FilenameFilter;

import java.io.InputStreamReader;

import java.io.OutputStreamWriter;

import java.nio.charset.Charset;

import java.text.MessageFormat;

@@ -137,21 +135,67 @@
                if (!params.skips.contains(documentName)) {

                    String fileName = documentName + ".html";

                    System.out.println(MessageFormat.format("  {0} => {1}", file.getName(),

                            fileName));

                    InputStreamReader reader = new InputStreamReader(new FileInputStream(file),

                            Charset.forName("UTF-8"));

                    String content = MarkdownUtils.transformMarkdown(reader);

                            fileName));					
                    String rawContent = FileUtils.readContent(file, "\n");

                    String markdownContent = rawContent;

					
                    Map<String, List<String>> nomarkdownMap = new HashMap<String, List<String>>();



                    // extract sections marked as no-markdown

                    int nmd = 0;

                    for (String token : params.nomarkdown) {

                        StringBuilder strippedContent = new StringBuilder();



                        String nomarkdownKey = "%NOMARKDOWN" + nmd + "%";

                        String[] kv = token.split(":", 2);

                        String beginToken = kv[0];

                        String endToken = kv[1];



                        // strip nomarkdown chunks from markdown and cache them

                        List<String> chunks = new Vector<String>();

                        int beginCode = 0;

                        int endCode = 0;

                        while ((beginCode = markdownContent.indexOf(beginToken, endCode)) > -1) {

                            if (endCode == 0) {

                                strippedContent.append(markdownContent.substring(0, beginCode));

                            } else {

                                strippedContent.append(markdownContent.substring(endCode, beginCode));

                            }							
                            strippedContent.append(nomarkdownKey);

                            endCode = markdownContent.indexOf(endToken, beginCode);

                            chunks.add(markdownContent.substring(beginCode, endCode));

                            nomarkdownMap.put(nomarkdownKey, chunks);

                        }



                        // get remainder of text

                        if (endCode < markdownContent.length()) {

                            strippedContent.append(markdownContent.substring(endCode, markdownContent.length()));

                        }

                        markdownContent = strippedContent.toString();

                        nmd++;						
                    }



                    // transform markdown to html

                    String content = transformMarkdown(markdownContent.toString());



                    // reinsert nomarkdown chunks

                    for (Map.Entry<String, List<String>> nomarkdown: nomarkdownMap.entrySet()) {

                        for (String chunk:nomarkdown.getValue()) {

                            content = content.replaceFirst(nomarkdown.getKey(), chunk);

                        }

                    }

					
                    for (String token : params.substitutions) {

                        String[] kv = token.split("=");

                        String[] kv = token.split("=", 2);

                        content = content.replace(kv[0], kv[1]);

                    }

                    for (String alias : params.properties) {

                        String[] kv = alias.split("=");

                        String[] kv = alias.split("=", 2);

                        String loadedContent = generatePropertiesContent(new File(kv[1]));

                        content = content.replace(kv[0], loadedContent);

                    }

                    for (String alias : params.loads) {

                        String[] kv = alias.split("=");

                        String[] kv = alias.split("=" ,2);

                        String loadedContent = FileUtils.readContent(new File(kv[1]), "\n");

                        loadedContent = StringUtils.escapeForHtml(loadedContent, false);

                        loadedContent = StringUtils.breakLinesForHtml(loadedContent);

@@ -165,7 +209,6 @@
                    }

                    writer.write(content);

                    writer.write(footer);

                    reader.close();

                    writer.close();

                }

            } catch (Throwable t) {

@@ -304,5 +347,8 @@
        @Parameter(names = { "--properties" }, description = "%TOKEN%=filename", required = false)

        public List<String> properties = new ArrayList<String>();



        @Parameter(names = { "--nomarkdown" }, description = "%STARTTOKEN%:%ENDTOKEN%", required = false)

        public List<String> nomarkdown = new ArrayList<String>();



    }

}