Introduction
Git is a source (and file) management system.
MUSHclient world files are text (human readable) files.
Thus it makes sense to use Git to track changes to your world files (and also as a side-effect, make backups of them).
You can read about Git here.
Very helpful online book about Git by Scott Chacon.
In the examples below, what you type is in bold type.
Why use source control?
- Once you commit a change, it is effectively backed up. Thus if you accidentally modify or delete something, you can go back to the backed-up version.
- If something goes wrong you can compare versions (using "git diff"). The differences can help you find what you did wrong.
- You have a log of what you changed, and when you changed them.
(Note: the files are backed up in the sense that a copy is made. This doesn't help if your entire hard disk crashes. To guard against that you should back up regularly to a totally different disk).
Installation
To download:
Download Git for Windows
After downloading, run the installer, taking the default options. You should then have a "Git Bash" icon on your desktop.
Getting started
If you double-click that icon you should see a "Bash Shell". This is a command-line style window into which you type commands. The commands are like the ones you use for Linux, however we won't have to do a lot of complex stuff.
You should see a dollar sign prompt. I will show these in the examples below, however you don't type the "$" symbol.
First, let's change to the MUSHclient world directory. If you have a standard installation it will probably be something like this:
$ cd '/c/Program Files/MUSHclient/worlds'
If not, type "cd " (don't forget the space) and then drag your "worlds" folder onto the command-line window and let go. It will copy the folder pathname into the window. Then hit <enter>.
You can type "ls" to list files in the directory.
In my example case I just have a Smaug.MCL file (the MUSHclient world file for my Smaug server) plus a plugins sub-folder.
Tell Git about yourself
To avoid any error messages, and to help with documentation later on, tell Git your name and email address:
$ git config --global user.name "Joe Bloggs"
$ git config --global user.email "joe@bloggs.com"
You only have to do this once. The --global option means it will affect all Git repositories on your hard disk.
Initialize this repository
I want to track world files in the "worlds" directory. Since I am now in the "worlds" directory I need to initialize Git in that directory.
Just to check, I can type "pwd" (print working directory) to see what the current directory is:
$ pwd
/c/Program Files/MUSHclient/worlds
This looks correct, so we'll initialize Git:
$ git init
Initialized empty Git repository in c:/Program Files/MUSHclient/worlds/.git/
Tell MUSHclient not to save dates to the world file
MUSHclient normally puts the date saved inside each world file. This is probably a bit of overkill, as the file date itself should tell you when it is saved. From version 4.92 onwards you can tell MUSHclient to omit that information. Inside MUSHclient, open an Immediate scripting window (Ctrl+I) and type:
SetOption ("omit_date_from_save_files", 1)
This assumes you are using Lua as your scripting language. This will set the option to omit those dates.
The reason for doing this it to avoid spurious differences being generated by "git diff" which are merely that the file has been saved at a later date and time (even if nothing else changed).
If you have only just done that, save your world again, to save it without dates all through the various parts of it.
Add your world file(s)
Back to the Bash shell prompt now, I added my world file like this:
If you have a lot of world files you can add them like this:
At this point your file(s) are known to Git, but not yet committed to the repository. So we'll do an initial commit, like this:
$ git commit -m "Initial commit"
[master (root-commit) 8683a3e] Initial commit
1 file changed, 457 insertions(+)
create mode 100644 Smaug.MCL
My world file, in its current state, is now committed to the repository. This means I can get it back later if I want (so it is, in effect, backed up) and I can also find out later what changes have been made, compared to the committed version.
Making changes, finding out what they are
Let's add a new trigger to the world file. Inside MUSHclient I'll add this trigger:
<triggers>
<trigger
enabled="y"
match="Exits: *"
send_to="12"
sequence="100"
>
<send>exits = "%1"</send>
</trigger>
</triggers>
 |
For advice on how to copy the above, and paste it into MUSHclient, please see Pasting XML.
|
Now save the world file (Ctrl+S) and then we will use Git to find out what changes we just made:
$ git diff
diff --git a/Smaug.MCL b/Smaug.MCL
index 1d608a2..225efc1 100644
--- a/Smaug.MCL
+++ b/Smaug.MCL
@@ -120,6 +120,14 @@ mana = %2
movement = %3
</send>
</trigger>
+ <trigger
+ enabled="y"
+ match="Exits: *"
+ send_to="12"
+ sequence="100"
+ >
+ <send>exits = "%1"</send>
+ </trigger>
</triggers>
<!-- aliases -->
The lines above tell us that there is a new trigger. The trigger is the lines with the "+" at the start of them. That means this is added information in the world file.
Committing a change
You don't have to commit every change, but once you have tested some changes, and are happy with them, it is a good time to commit them. That way you can always go back to that version.
$ git commit -a -m "Added a trigger to detect exits"
[master 1d3e3de] Added a trigger to detect exits
1 file changed, 8 insertions(+)
The message in quotes (-m option) is a description which should provide a helpful note to yourself about what is in this particular commit.
The -a option tells Git to add any changed files into this commit.
Get a log of changes
The "git log" command tells you of all the commits you made (by default with the most recent first, but you can change that):
$ git log
commit 1d3e3deeaab12efdcd66aec15e1ef94b23139e62
Author: Joe Bloggs <joe@bloggs.com>
Date: Sun Apr 20 10:58:45 2014 +1000
Added a trigger to detect exits
commit 8683a3e1027e799ec2f4eceac9f93e9867712caa
Author: Joe Bloggs <joe@bloggs.com>
Date: Sun Apr 20 10:56:04 2014 +1000
Initial commit
Get the status of your directory
We can find a summary of what our status is with "git status" :
$ git status
On branch master
Untracked files:
(use "git add <file>..." to include in what will be committed)
plugins/
nothing added to commit but untracked files present (use "git add" to track)
Notice that Git is telling us about the plugins directory, which is currently not being tracked by Git. If you are writing your own plugins you can track them, by adding them to Git:
$ git add plugins
$ git commit -m "Initial commit of plugins"
Alternatively, use Notepad or any text editor to make a ".gitignore" file (note the leading period in the file name).
We can tell Git to ignore the plugins directory, plus the .gitignore file itself, by putting this inside that file:
That tells Git to ignore all files starting with a period, and also the file (or directory) called "plugins".
Once we have created that file, typing "git status" gives us a "clean" working directory:
$ git status
On branch master
nothing to commit, working directory clean
Once I make further changes, typing "git status" reveals what is changed:
$ git status
On branch master
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: Smaug.MCL
no changes added to commit (use "git add" and/or "git commit -a")
It helpfully tells us how to add and commit that file, and also how to go back to the previous version. For example, if I didn't like the change I just made I can checkout (go back to) the previous version:
GUI interface
There is also a graphical (GUI) interface to Git which comes as part of that install. You may find that easier to use. It should be found in Program Files called "Git GUI".
For example, after making a change (and hitting the Rescan) button, I see this:
You can see there that I added something to the world "notes" configuration tab.
Then I hit the "Stage Changed" button to add the changed files:
(This is the same as typing: "git add Smaug.MCL")
Finally I can type in a reason for the commit in the Commit Message box on the lower-right side, and hit the "Commit" button. The result after that is:
Now there are no staged or unstaged changes, and the status line at the bottom shows the commit number and commit message. |
![[Go to top]](/images/gototop.gif){kind=small}
top