[Home] [Downloads] [Search] [Help/forum]

Gammon Forum

See www.mushclient.com/spam for dealing with forum spam. Please read the MUSHclient FAQ!

[Folder]  Entire forum
-> [Folder]  MUSHclient
. -> [Folder]  Tips and tricks
. . -> [Subject]  How to use Git to manage your MUSHclient world files
Home  |  Users  |  Search  |  FAQ
Username:
Register forum user name
Password:
Forgotten password?

How to use Git to manage your MUSHclient world files

It is now over 60 days since the last post. This thread is closed.     [Refresh] Refresh page


Posted by Nick Gammon   Australia  (21,321 posts)  [Biography] bio   Forum Administrator
Date Sun 20 Apr 2014 04:14 AM (UTC)

Amended on Wed 18 Jun 2014 03:55 AM (UTC) by Nick Gammon

Message
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.


$ ls
Smaug.MCL  plugins


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:


$ git add Smaug.MCL


If you have a lot of world files you can add them like this:


$ git add '*.MCL'


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>


Template:pasting 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:


.*
plugins


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:


$ git checkout Smaug.MCL


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.

- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

Posted by Nick Gammon   Australia  (21,321 posts)  [Biography] bio   Forum Administrator
Date Reply #1 on Wed 01 Oct 2014 02:17 AM (UTC)
Message
More notes about Git here:

http://www.gammon.com.au/forum/?id=12512&reply=4#reply4

- Nick Gammon

www.gammon.com.au, www.mushclient.com
[Go to top] top

The dates and times for posts above are shown in Universal Co-ordinated Time (UTC).

To show them in your local time you can join the forum, and then set the 'time correction' field in your profile to the number of hours difference between your location and UTC time.


3,343 views.

It is now over 60 days since the last post. This thread is closed.     [Refresh] Refresh page

Go to topic:           Search the forum


[Go to top] top

Quick links: MUSHclient. MUSHclient help. Forum shortcuts. Posting templates. Lua modules. Lua documentation.

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.

[Home]


Written by Nick Gammon - 5K   profile for Nick Gammon on Stack Exchange, a network of free, community-driven Q&A sites   Marriage equality

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( https://gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Hosted at FutureQuest]