This section covers various points about managing and maintaining a Wiki. This is from the point of view of using a text editor on local machine to modify the Wiki.

In particular, using Visual Studio Code (VS Code) as the text editor for the Wiki and then using the facilities of VS Code to push any modifications to GitHub.

This section covers the following:

This section is largely based on what I have come to understand by developing Wikis for the PracticalSeries of publications. None of it is essential, but some of it may be useful to you.

⬆️ Top

Here we go then.

A Wiki is a (restricted) repository in its own right (see section 1.4). It is restricted because GitHub doesn’t give all the facilities available to a normal repository to a Wiki, you cannot, for example, have branches within a Wiki repository (GitHub just ignores them and only works with the Master branch).

Now, when you clone a repository to a local machine (see section 2) and open it in some Git friendly text editor (VS Code for example) you get the full facilities available for managing any repository and you can apply them all to the Wiki — you can, for example, create branches within the Wiki and push them back to GitHub, only to have GitHub ignore them completely.

So, while you have all the facilities to manage the Wiki as a full-blown repository, it is best to scale down your ambitions and just use those facilities that GitHub wants you to

So here’s my guide:

Don’t think of the Wiki as a development environment where you can create branches, assign them to different development teams and merge everything back together at some later date.

${\huge \color{#C00000}\text{Think\ of\ a\ Wiki\ as\ a\ document\ that\ only\ one\ person\ can\ work\ on\ at\ a\ time.}}$

Each time the document is changed and reposted to GitHub, the document revision is updated.

Obviously, more than one person can clone the Wiki and each person can modify bits of it as they like, but there is no structure (like branches) that allows for different development paths or group working. Essentially, you would have to incorporate everybody else’s changes into your cloned copy before pushing your own changes back to GitHub. It’s a bit of a nightmare.

The best mechanism for managing a Wiki that I’ve come up with, is to have a single person controlling the Wiki, let’s call them the “Lead” (in my case, it is me).

That person sets up the underlying folder structure and pushes the result to GitHub.

If someone else wants to work on the Wiki, the Lead sets up a new folder in the structure and assigns it to that person, that person can work in that folder (add, delete, change files &c.), but only in that folder (no other part of the Wiki).

This process is repeated for each person working on the Wiki, the each get their own folder.

When an individual changes a file in their folder and wants to push it to GitHub to test it, they must first pull any other changes made to the Wiki to their local machine. Since all these changes will have been made in other folders (allocated to other people), there will be no impact on the local modified files. The whole lot can then be pushed back to GitHub.

Where common files or files in directories outside an individual’s development folder, these must be managed by the Lead.

⬆️ Top

When I first started writing a Wiki, I was meticulous about commit messages (as I am with a proper repository), it rapidly dawned on me that this was a pointless exercise.

This is a screen shot of part of my modification history for this Wiki:

Figure 17.1 — Wiki development revisions

There are pages of it. At the time of writing I’d made 2,229 commits to the Wiki and they all had the same commit message:

   🚧 Wiki construction — initial development

While you are developing a Wiki, there is absolutely no point in trying to record changes or manage the revisions in anyway. Think how many changes you make to a Word document, spelling mistakes, changing an image, updating the contents and links, not to mention incorporating comments from other people.

There are thousands of changes and not much point in trying to explain each one, at best you enter commit message such as: “typographical corrections”, “incorporated comments from MG” &c. Such commit messages do not impart much information.

The only useful information for previous commits is the date of the commit. Along the lines of: “I’m pretty sure that section was OK last Tuesday, let’s load that one and see what I screwed up in the meantime”.

It’s different once the Wiki is complete, reviewed and published. At that point, changes will be fewer and probably associated with a revision of a particular section &c. Under these circumstances more meaningful commits may be a practical option.

Until then don’t worry about commit messages.

In VS Code, with Source Control active, there is a list of the most recent commits in the left-pane. If you right-click one of these messages you can copy the commit message and just paste it into the commit box at the top and then commit the changes. It's an easy way to re-use the same commit message.

⬆️ Top

GitHub can display the history of any Wiki page (this was discussed in section 1.4.1). Broadly, go to the Wiki page you want to see the history of and click the revisions link (this is in the title area of the page, just below the title text).

This is the current history for the Home page of this repository:

Figure 17.2 — Wiki page revision

As was said in section 1.4.1, this history isn’t particularly useful, for a start you cannot see the complete history for the whole Wiki, just a page at a time.

The only practical use for the GitHub Wiki history is for finding the first commit number for the Wiki. This is only needed if you rebase the Wiki to get rid of all the commits that accrue in the creation process (this is discussed in detail in the next section).

To find the first commit for the repository, go to the Home page of the Wiki and click the revisions link at the top-left of the page to open the history page (shown above).

Scroll to the bottom of the page and keep clicking Older until you get to the oldest commit:

Figure 17.3 — Wiki first commit

The first commit for this Wiki is dd06e43.

This is the easiest way to find the first commit number for the Wiki (the home page is the first page to be created when starting the Wiki).

You may be wondering why it important to know the first commit point?

The answer is: it isn’t, not unless you want to purge all the commits that have been made (apart from the first one) and reload the current state of the pages back in as the second commit point (I.e. to essentially reset the repository and remove all the many commits that have been made in the meantime).

I discuss this process in the next section.

⬆️ Top

Rebasing scares the shit out of most people, no one really understands it and if you get it wrong you can lose all your stuff.

I have a golden rule about rebase: ${\huge \color{#C00000}\text{Never\ use\ rebase.}}$

So why do I want to use it?

Well, what I’m describing here breaks most of the rules about version control and repositories, but it can be used to tidy up all those unwanted commits in a Wiki.

Let’s say you find yourself in the position that I’m in: I’ve finished the Wiki and I want to publish it to GitHub, but I’ve got 2000+ commits from developing, testing, correcting &c. and I don’t want any of them. Essentially, what I want is for the finished version to be the first (or more practically, the second) commit.

In short, I don’t want all the intervening commits for every spelling correction and minor document tweak that was made. I want to go from the initial commit (when the Wiki was created) to the finished article.

${\huge \color{#C00000}\text{Yep,\ it\ breaks\ the\ basic\ rule\ of\ a\ version\ control\ system.}}$

My thought process was this: I’m never going to wade through 2000 commit point looking for a particular change, so what’s the point in having them. Surely it is better to get rid of all those commits and start with the finished article. I can then monitor the commits from there on, these being more relevant, smaller in scope and more traceable.

That said, this process is brutal and is not for the faint hearted. I would practice it on a development Wiki that you don’t care about first.

⬆️ Top

To summarise, the process does the following (I've included this so you know what will happen before you actually do it for real):

That’s the theory, this is how you do it:

⬆️ Top

This is the step-by-step guide (with pictures).

①	Commit any outstanding changes to the Wiki repository and synchronise everything with GitHub
②	Identify the very first commit point for the Wiki using the mechanism given in section 17.2. In my case the commit point is: dd06e43
③	Using Windows File Explorer navigate to the Wiki folder, in my case it looks like this: Make sure that the folder has a .git directory within it (highlighted)
④	Copy the folder (in my case the GitHub-Wiki-Design-and-Implementation.wiki folder) and paste it into some other location — I.e. make a backup of the whole Wiki repository Make sure the backup has the .git directory within it
⑤	In VS Code, select ${\color{#00B050}\langle\text{Terminal}\rangle}$ and then ${\color{#00B050}\langle\text{New\ Terminal}\rangle}$ to open the Git terminal Window at the bottom:
⑥	The terminal window looks like this:
⑦	Enter the command: ${\large \color{#0050C0}\text{git\ reset\ --hard\ }\color{#C00000}\text{[commitNo]}}$ Where ${\large \color{#C00000}\text{[commitNo]}}$ is the first commit point number, in my case it is ${\large \color{#0050C0}\text{git\ reset\ --hard\ dd06e43}}$
⑧	The repository now only has the single Home.md file within it (everything else has gone)
⑨	Now go to the backup created in step ④ and select everything apart from the .git directory
⑩	Copy the selection (everything but the .git directory) from the backup. Navigate to the proper repository and paste it in (replacing the Home.md file in the process)
⑪	VS Code will now show a large number of new files (533 changes in my case):
⑫	Stage all the files, enter a commit message and commit the changes: ${\large \color{#C00000}\text{DO\ NOT\ SYNC\ THE\ REPOSITORY\ IF\ PROMPTED\ TO\ DO\ SO}}$
⑬	At this stage, the Wiki on the GitHub site is still as it was, it has a full history of all the commits made. If we were to sync the local repository and GitHub, everything would just be copied back from GitHub and everything would be as it was
⑭	The local repository currently just has two commits (the original one, and the one we have just made by adding all the files back in). To make those changes permanent, the local Wiki must be pushed to GitHub overwriting what is there. This requires a forced push (i.e. it pushes the changes to GitHub without pulling any existing changes first). In the terminal, enter the command: ${\large \color{#0050C0}\text{git\ push\ origin\ HEAD\ --force}}$
⑮	After a short period, it comes back with a response, this was mine:
⑯	Looking at the history, the Wiki now has (in my case): There are just two commits, the original commit (when the Wiki was created) and now the second commit with all the files back where they should be. I.e. all the intervening commits are gone and the Wiki is back in the same state as it was at the final commit before all this started
	List 17.3 — Executing the rebase process

Not nerve wracking at all.

This is a confusing topic and I’m not clear what the situation is.

Currently, search engines are allowed to craw GitHub Wiki files, at least they are not excluded in the GitHub.com robots.txt file:

# If you would like to crawl GitHub contact us 
# via https://support.github.com?tags=dotcom-robots
# We also provide an extensive API: 
# https://docs.github.com
User-agent: baidu
crawl-delay: 1


User-agent: *

Disallow: /*/*/pulse
Disallow: /*/*/projects
Disallow: /*/*/forks
Disallow: /*/*/issues/new
Disallow: /*/*/issues/search
Disallow: /*/*/commits/
Disallow: /*/*/branches
Disallow: /*/*/contributors
Disallow: /*/*/tags
Disallow: /*/*/stargazers
Disallow: /*/*/watchers
Disallow: /*/*/network
Disallow: /*/*/graphs
Disallow: /*/*/compare

Disallow: /*/tree/
Disallow: /gist/
Disallow: /*/download
Disallow: /*/revisions
Disallow: /*/commits/*?author
Disallow: /*/commits/*?path
Disallow: /*/comments
Disallow: /*/archive/
Disallow: /*/blame/
Disallow: /*/raw/

Disallow: /*/cache/
Disallow: /.git/
Disallow: */.git/
Disallow: /*.git$
Disallow: /search/advanced
Disallow: /search$
Disallow: /*q=
Disallow: /*.atom$
Disallow: /ekansa/Open-Context-Data
Disallow: /ekansa/opencontext-*
Disallow: */tarball/
Disallow: */zipball/

Disallow: /*source=*
Disallow: /*ref_cta=*
Disallow: /*plan=*
Disallow: /*return_to=*
Disallow: /*ref_loc=*
Disallow: /*setup_organization=*
Disallow: /*source_repo=*
Disallow: /*ref_page=*
Disallow: /*source=*
Disallow: /*referrer=*
Disallow: /*report=*
Disallow: /*author=*
Disallow: /*since=*
Disallow: /*until=*
Disallow: /*commits?author=*
Disallow: /*report-abuse?report=*
Disallow: /*tab=*
Allow: /*?tab=achievements&achievement=*

Disallow: /account-login
Disallow: /Explodingstuff/

That said, the GitHub documentations (here) says the following:

“Search engines will only index wikis with 500 or more stars that you configure to prevent public editing.” I don’t have 500 stars, so I can’t tell if this is true

“Search engines will only index wikis with 500 or more stars that you configure to prevent public editing.”

I don’t have 500 stars, so I can’t tell if this is true

I’ve also noted that when I’ve searched for things in the process of writing this, GitHub Wikis tend not to come up in the search results.

Either way, if your Wiki is configured for public editing (see here) it won’t feature in

To turn this off, click ${\large \color{#00B050}\langle\text{Settings}\rangle}$ for the repository, select ${\large \color{#00B050}\langle\text{General}\rangle}$ in the left-hand menu bar and then in the Features area (main section) tick the ${\large \color{#00B050}\langle\text{Restrict\ editing...}\rangle}$ box:

GitHub Wikis are definitely searchable from the GitHub search box.