Using Gitlit¶
Getting started¶
There are two possible use cases for gitlit:
- Using the tool for its purpose of structured document management.
- Using the tool to ensure it is working when developing for it.
In the former case, currently, the means of installing it would be through NPM. If NPM is installed on they system, simply run:
npm install -g gitlit
To run any of the commands discussed here, simply use:
gitlit <command info>
If contributing to the project, then inside the GitHub project folder, at the root (where the package.json file is), simply run:
node ./cli/gitlit.js <command info>
- Alternatively:
- ./cli/gitlit.js <command info>
Note
For all of the sections following this, the information given will be what is meant to go into <command info>. So, if you were using the tool for it’s purpose, and you wanted to initialize a repository, the command might be given as:
init source-file . outputRepo
but note that this is prefixed by the necessary command to run the tool based on why you are trying to run it.
Creating a repository¶
The command for creating a repository given an HTML document is:
init <file> <location for repo to be made> <repo name>
So an example command might look like:
gitlit init test.html /usr/root/docs first-repo
Take note that the 2nd argument needs to be a location that already exists, as what actually happens is a directory is made at that location with the name <repo name>
So, if the above command was run, the directory /usr/root/docs/first-repo would then be made.
If it existed before, an error will be thrown stating as such.
Note
If there are missing tags in the HTML document, such as a missing opening tag, the parser used by gitlit will take it’s best guess as to what was intended. Since there are most likely many possibilities, the possibility chosen may not be what the user meant. If you want to be certain this doesn’t happen, ensure that the HTML is valid, preferably through The W3C Validator.
Generating HTML from a repository¶
To generate a file from a repository, simply run:
write <path to repository directory> <path of output file>
An example command might look like:
gitlit write /usr/root/docs/first-repo ./test.html
Which would generate an HTML file called “test.html” in the current directory, with its source being the repository “first-repo” at /user/root/docs.
If the output file existed before, its contents will be overwritten so take caution.
Note
The contents of the HTML file will be pretty-printed as reasonably as possible. Due to the complex nature of HTML and the fact that gitlit wants to make only meaningful notes about differences between different versions of a document, some quantity of formatting (i.e. whitespace) is lost, and as such, the formatting is not kept exactly the same. That being said, the formatting is still decent, and is quite readable.
Note
After generating the file, you likely noticed the attributes that got added to many of the tags called “por-id”. These attributes are tracking ID’s used to aid in recognition of sections even if the subsections or text is changed. As such, don’t alter or remove the por-id’s unless the document is completely finished being developed, as this will cause gitlit to give very unhelpful diffs when comparing different versions of a document.
Making a commit¶
Once a repository is created, a new revision can be tracked in the repository through making a new commit. Just like git, and differences will be stored into a new commit and the repository will be at this new revision, with the history stored in the commit history.
Since gitlit works on a document as a whole, commits are made by providing a new document. This removes the need for users to edit the files split by the tool, and makes it easier to view the document as a whole will editing.
To make a commit, just run:
commit <file for new revision> <path to repo directory> <commit message>
An example command would look like:
gitlit commit ./test.html /usr/root/docs/first-repo "Changed page title"
After this command is made, the Git repository that is the basis for that gitlit repository will have a new commit, and the whole directory structure will be in a state the reflects the new revision.
If a write command is run on this repository now, the outputted document will look nearly identical to the input document given in the above command. (Nearly identical because of some likely formatting of the document, and perhaps por-id’s added for new sections).