Getting Started

So you want to dig a burrow...

Getting started with Gopher and burrow is easy. Follow the steps below to get going:

1. Grab a copy of burrow

You can either clone this repo or download a zip package from the most recent release.

2. Install or use locally

If you have root access on your machine you can install burrow with sudo make install from inside the downloaded repo, or the folder that is created from the zip you downloaded. If you are on OSX, you may need to install a few dependencies which are all listed at the top of the README. These are to ensure you have the GNU version of common programs like bash sed and getopt.

If you do not have root access on your machine, you can run the burrow script from that directory as-is by typing ./burrow or path/to/burrow. You won't get the extra help from the man page or the tab completion this way, though.

3. Make sure you have a gopher hole

If you don't actually have a gopher hole set up somewhere, I recommend signing up for a free account at SDF.org.

4. Generate a configuration file

The first thing you should run with burrow is burrow create-config. This will generate a configuration file at ~/.config/burrow/config. You'll want to open and edit this file right away and change the settings to match your gopher preferences and locations.

At the minimum you will need to update these settings to match your system:

config_dir_gopher="/absolute/path/to/your/gopherhole/"
config_gopher_server="sdf.org"
config_gopher_port="70" # if you don't know this, it's probably 70
config_gopher_root="/users/tomasino/"

5. Create a top-level gophermap

Burrow is helpful in creating individual phlog posts, adding recipes, or making notes on topics. It does not create your top-level gophermap, though. If you are brand new to gopher and looking for a generic one to get started, I would recommend:

 ==== Last Updated: March 01st, 2018 ====
1Phlog	phlog	your.host	70
1Recipe Box	recipebox	your.host	70
1Topics	topics	your.host	70

Those fields are separated by actual tabs, not spaces. That's very important in gopher. This very basic gophermap will allow visitors to your gopher hole to find your phlog posts, recipes, and topic notes. As soon as you use burrow to create individual entries everything should wire itself together, and that Last Updated date will automatically change.

---

Appendix A. Ask for help

I hang out on irc at irc.sdf.org in #gopher. Feel free to ask me any questions you might have.

Appendix B. Common problems

Well, there's not many users of burrow just yet, so I'm not sure how common these are. Still, it's good to summarize them somewhere.

Problem: I can't get my gopher hole to auto-update git on SDF cluster using burrow

What an extremely specific issue! If you are trying to auto-update your gopher content using git, you have probably set up a cron job to do so. You may have decided to use burrow update-git as the command to run. Unfortunately, burrow requires GNU getopt to parse the command line parameters and SDF's cluster has a small issue. By default cron runs in a minimal shell with a PATH that has /usr/bin listed before /usr/pkg/bin. There's a non-GNU version of getopt in /usr/bin, and that breaks everything.

My advice, set up a cron job to change to your gopher directory and run git pull -q. You don't need burrow for that.