A Game Design Document will Focus your Work

Introduction

Have you tried to create a large game project and got lost in the weeds? It is very easy to do.  If you were working for a AAA game development company (like Epic Games), that probably would not be a problem, because the company would have a YUGE staff for all phases of game development, and you would have maybe a 100- or 1000- page Game Design Document.  This would detail everything that needs to be done in the game, and it will have been reviewed multiple times by perhaps 100s of employees (developers, designers, testers, artists, management, and so on) (though even with all that, it may be changed as more is learned!)  so you always know what needs to be done and how it fits with the rest of the game.

Now, at the other extreme, suppose you are a one-person game studio.  You are it! You are the designer, developer, artist, manager, and janitor.  You might not relish the idea of writing a 1000-page Game Design Document (GDD) all by yourself, and not only that, reviewing it, editing it, making sure it is all consistent (with itself and with available technology), and so on.  The good news is, you don’t have to in order to reap benefits when you find your self headed for the rough.

At the smallest extreme, you can write a one-page GDD that hits the highlights.  This is far better than nothing at all, even if it isn’t as detailed and well-reviewed as the AAA Game Development Company’s 1000-page GDD.

If you want more, a 10- or 20-page GDD gives additional benefits.   20 pages easily helps you focus enough that even if you find yourself in the weeds, you can see the way out.

If you are a 10-person game studio, 10 or 20 pages would be the minimum, and you could probably produce larger, with more editing and review.  My point is smallness of company is no excuse for not planning at all.  Just plan less!

Core Components of a Game Design Document

A Game Design Document (GDD) will likely contain at least the following  information:  title of game (or working title if not finalized yet), genre of game (first-person shooter, puzzle, classic arcade, etc.), technology used (Unreal Engine 4? Unity?), platform (PC/Mac/Linux, Android, etc.) and a brief description of the game.

I recommend more than one description, of varying lengths (for varying purposes).

The tag line is a one-sentence description of the game.  This gives more of a taste than a picture.  An example tagline (from a movie rather than a game) is, “In space, nobody can hear you scream”, which was used on movie posters for Alien when it first came out.  This drew the crowds by giving a flavor of what the movie was like: terror in space.

The elevator pitch is a one- or two-paragraph description of the game.  The name comes from this: you work for a company and you happen to find yourself in an elevator car with the CEO, and the CEO asks, “what are you working on?”  In the time it takes to get to your floor, you need to explain what you are doing, and of course, make it sound like it’s worth the salary you are being paid.

Finally, a longer Summary of the game gives a good picture of what is happening when somebody plays it.  If it is a multi-page GDD, go ahead and use one or two pages for the summary.  If it is a one-page GDD, you might skip it (or just consider the rest of the document to be the summary).

If the game has an unusual key mechanic, it should go in the summary, or perhaps in a section of its own.  What I mean by “mechanic” is how the game is played: jiggle the joystick back and forth to make the character run, and jiggling faster makes the character run faster.  Pressing a button makes the character jump.  (I vaguely recall an Atari console game like that).  It’s not always necessary to explain the mechanic.  For example, most First Person Shooters work the same way.  Still, you might want to explain unusual moves (dodging, double-jumping, wall-walking, turn into a spirit like in Prey, etc.)

Other Components

Assets needed for the game should be specified.  For a one-page GDD, it would be a summary of assets and style for them, but for a more detailed GDD, you can get really detailed if you want.

Rules of the game should be specified.  Think of a boxed board game: often  on the inside cover of the box, the rules of the game were printed.  This would include things like win or lose conditions, mid-game achievements (like how the player would end one level and start another), if and how it is scored, how powerups and pickups affect the game, and so on.

Depending on the game, a section for research might be appropriate.  For example, if you are making a bowling game, you might have a section giving all the specifications of bowling determined through online research: lane dimensions, markings on lanes, pin sizes and weights, ball size and weights, and so on.

In addition to data from research done, this section can mention research that still needs to be done.  As the research is completed, the section can be edited to show that.

Sample Game Design Document

Here is a (incomplete, but a good start)  GDD for a 3D bowling game.

Game Overview

Working Title

Precision Bowl

Genre

Sports Game

Audience

Adult

Tag Line

Set up ball speed and spin, choose your target, and try to bowl a perfect game!

Elevator Pitch

Choose a bowler character to select strength and speed as well as appearance.  Choose a bowling alley, as well as normal or outer space lighting.  Choose a ball to select weight, outer coating, and optional asymmetric weight block, as well as appearance.  Choose an alternate spare ball if you want.  Choose a lane and oil pattern.  Then start bowling!

Select a spot.  Select a target.  Adjust speed up or down.  Adjust spin.  Choose to use strike ball or spare ball.  Hit “Go” and watch the bowler follow your commands.   Score!

Key mechanic

Physics, Physics, Physics!  Player takes all the time they want setting it up, then hit Go and it’s all physics!

Assets

Meshes

Ball, Pin, Lane , Bowler character(s), Sweeper, Pin Setter, Ball Return, Gutter, Monitor

Alley features: tables, other lanes, back wall, ceiling, other walls and floors, snack bar, juke box, entrance, restrooms, ball washer, front desk and shoe rental, people?

Materials and Textures

Various ball patterns, normal and space light (cosmic or galactic bowling type of situation, with UV lights)

Standard pin and special pins (e.g. red pin), normal and space light

Wood or composite lane, with oil patterns, normal and space light

Bowling alley features materials, normal and space light

Character skins, normal and space light

Sweeper material, normal and space light

Pin Setter materials, normal and space light

Ball Return materials, normal and space light

Gutter materials, normal and space light

Monitor UI material

Animations

Bowling animations for character, including right-hand, left-hand, and for backup ball, straight ball, and spin ball.

Camera animations, Sweeper animation, Pin setter animations, Ball return animations

Sounds

bowler talk, ball rolling, Pin hits, Ball return sounds, Music, Announcer voice, Ambient bowling alley sounds

Actors and Actions

Ball

Attach to character, Roll, Drop, Destroy, Initialize

Pin

Destroy, Initialize

Bowler

Take Ball, Drop Ball, Roll Ball

Ball Return

Spawn ball

Sweeper

Deploy

Pin Setter

Reset Ball, Reset Frame

Monitor

Update

Camera

Follow Character, Follow Ball, Overview Lane

Research needed

  • Standard bowling lane, standard bowling balls, standard oil patterns, standard pins, standard pin layout
  • Ball return, pin area geometry
  • Bowling alley features
  • Physics: spin, oil patterns
  • Bowling terms, both “official” and informal
  • Bowling animations
  • Good camera animations
  • Sweeper and pin setter
  • Rules for scoring!

Technology

Unreal Engine 4.19.2 or above

More Information

How to Write a Game Design Document on Gamasutra

Sample FPS Game Design Document, 23 pages, team of two

 

Exporting the Mannequin Skeleton from Unreal Engine 4 to Blender and Re-importing

(Reprinted from Unreal Wiki)

Overview

Searching online, I see many (like me) have wanted to work on characters in Blender by exporting the Mannequin skeleton provided by Epic, but there are problems with doing this. The older versions of Unreal Engine 4 it just doesn’t work, apparently, but the later versions, I got it to mostly work by searching online, through the Udemy Blender Character Creator course, and through lots of trial-and-error.

I am using Unreal Engine version 4.18, but it should be similar in recent engine versions. I’m also using Blender 2.79, again should work in recent Blender versions (2.8 and above is supposed to be a major change in Blender so it might fail there).

The first job is to export the mannequin so it can be used in Blender. Yeah, that’s 18 steps, but then the other jobs take lots of steps too…. This is not really a quick-and-easy job despite the humor in the next heading.

Exporting the Mannequin in 18 easy steps!

  1. Start with a UE4 project, an existing one or create a new one.
  2. Download, if you don’t already have it, the Animation Starter Pack available for free in the Marketplace.
    Marketplace Animation Starter Pack
  3. In the Epic Games Launcher, find the Animation Starter Pack in your vault and click Add to Project, and select the project you have created or chosen to use.
  4. Open your project. In the content directory, you should now see an AnimStarterPack folder.
  5. Navigate to the folder Content/AnimStarterPack/UE4_Mannequin/Mesh, then right-click the SK_Mannequin asset in the content browser. Select Asset Actions→ Export.
  6. Choose an appropriate directory and name (such as SK_Mannequin.fbx).
  7. An FBX Export Options window will appear. Blender uses FBX 7.4 which is the same as FBX 2014 (7.5 == 2015, 7.6==2016, and so on). So, change Fbx Export Compatibility to FBX 2014. All other options can be left as default. Unchecking Level of Detail and Collision should be harmless (I don’t think they have any effect on a skeletal mesh).FBX Import Options.png
  8. Click the Export button.
  9. Open Blender to a new scene and delete the default cube.
  10. In the menu bar at the top (assuming the default layout), select File→Import→FBX (.fbx).
  11. You will see a screen with (by default at the lower-left corner) an Import FBX panel.
  12. Select the Main tab in this panel and keep the default values, which look like this.Blender FBX Import Main Options
  13. Click the Armatures tab. A few settings do have to be changed from the defaults: UE4’s bone axes are a little different from the Blender default. Note changing the axes is optional—you might actually prefer the defaults! (I actually do, but googling shows many don’t). Of course, later when you export FBX from blender, make sure the axes settings are the same as the import axes settings!Blender FBX Import Armatures Options
  14. Optionally, click the plus sign (+) to the right of Operator Presets to save these settings, giving it a name like UE4. Then henceforth you can load the settings instantly by clicking on Operator Presets and selecting UE4 or whatever you named it.
  15. Navigate to the file you just exported from UE4 and select it, then click Import FBX.
  16. The model should appear in Blender. You might have to zoom to see it: It is 1.927 blender units high. Verify the skeleton is correct by selecting one of the bones (there are a few huge IK bones that are easy to select) to select the armature, and then in the Properties panel (by default to the right) with the Armature tab (looks like a little man with arms stretched out and a wide stance) selected, check the X-Ray box in the Display section. Annoyingly (and I know no workaround), the left-side bones are oriented in the opposite direction from the right-side bones. Also, while the bones are parented correctly, they are not actually connected—leave it like this, since “fixing” it will cause problems, as I was able to verify.
  17. One annoying change has to be made. The importer parents the armature to an empty. In the Outliner view, if you expand a couple levels, you will see the hierarchy with an empty having an armature child, having a mesh child.
  18. There is an SK_Mannequin empty, and its child is the “root” armature, and its child is the SK_Mannequin.001 (or something like that—the .001 might change) mesh. The empty is a problem: when you export from Blender and re-import into UE4, the empty turns into a new root bone and that fouls everything up. Don’t just delete it, that will not keep the transform of the children. Instead, select the “root” armature, then click (with the cursor in the 3D view window, and do this in Object mode) ALT-P, then select Clear and Keep Transformation. Now, you can delete the empty.

Now, you can work on your character. You probably want to replace the mesh with your own. I recommend not moving the bones around in Edit mode or Pose mode or it might confuse Unreal (Edit mode it definitely will, Pose mode might impact retargeting). Make your mesh, and parent it to the root armature. Unreal uses vertex groups for rigging, so either select create empty vertex groups and manually put vertices in the right groups, or select one of the options to convert bone weights to vertex groups or something like that. Test your rig in pose mode to make sure it still works right! Also unparent the original mannequin from the root armature (keep transformation if you want to keep the mannequin, or just delete the mannequin otherwise—I keep it around during modelling, making it semi-transparent, so you can have a reference for the right humanoid proportions compatible with the rig).

Now that you have your new character with Unreal’s Mannequin rig, you want to get it back into UE4.

But if you are only testing, ignore those last two paragraphs and just re-import the mannequin to see that this works right.

Get Your Character From Blender Into Unreal Engine 4

  1. Use the A key once or twice to ensure nothing else is selected. Then Ctrl-click in the Outliner to select the Root Armature and all (one) of its children.
  2. Now that the armature and its child mesh are selected, in the menu bar, select File→Export→FBX (.fbx).
  3. To export properly, lots of export settings must be changed. Here they are (and optionally, save them as a preset so you can select these settings instantly in the future). There are more tabs to select in the export dialog than in the import dialog: Main, Geometries, Armatures, and Animation. (the last is relevant only if you are exporting animations). Note if you used the default axes for importing FBX, you must use those same axes settings for exporting FBX.
    Blender FBX Exporting the Mannequin Main Options
    Blender FBX Export Mannequin Geometries Options
    Blender FBX Export Armatures Options
    Blender FBX Export Animations Options
  4. Switch to an appropriate directory and choose a name to save the .fbx file to. For the test, the author chose SK_Mannequin2.fbx so as not to overwrite the original mannequin export.
  5. In Unreal, in the Content Browser, click the Import button.
  6. Navigate to the proper directory and select the file to import (such as SK_Mannequin2.fbx). Then click Open.
  7. The FBX Import Options window pops up. Most of the default values can be left as-is but here are some changes.
  8. There are two ways that can work now. If you made significant changes to the character, you might have no choice but to use the annoyingly complex Option 2. If not, the simpler Option 1 can be done. So now we fork and exec two procedures. If you try Option 1 and it fails, delete the imported assets, redo the steps in this section, and then go to Option 2.

Completing the Import into Unreal, Option 1: using the same Mannequin skeleton

  1. Select the FBX Import Options as follows (mostly the defaults, a few changes):
    FBX Import Options 1
    FBX Import Options 2
  2. As you see, this option imports and keeps the old skeleton. Click Import All, and look at your new assets (e.g. SK_Mannequin2 and SK_Mannequin2_PhysicsAsset). Open these up and make sure they look right. You will have to set the materials appropriately on the mesh, or skip that if you are just testing.
  3. To really test, navigate to Content/AnimStarterPack and find the blueprint UE4ASP_Character. Drag it into the scene.
  4. With the character selected in the scene, go to the Details panel (by default to the right),and select the Mesh component near the top of the panel in the Components section.
  5. Below the Transform and Animation sections, there is a Mesh section. Change the skeletal mesh from SK_Mannequin to your new mesh (e.g. SK_Mannequin2). When you play the game, the character should be in the idle pose, breathing and posed to hold a weapon. Optionally, set the character up as your game pawn and try that too (advanced topic). Also, go to the Content/AnimStarterPack directory and open several of the animations files and look at the animations and make sure arms aren’t being ripped out of sockets, head screwed on backward, etc.
  6. If your character is too different from the Mannequin, you will have problems, arms pulling out of sockets, things like that. In that case, Option 2 needs to be done instead, so delete your character from the scene, save the scene, then delete the assets that were imported (e.g. SK_Mannequin2 and SK_Mannequin2_PhysicsAsset), and start over with importing, but go to option 2 instead. If you get warning messages trying to delete, you might have to quit and restart the UE4 editor and possibly fix up redirectors as well. Ultimately, I had to ignore an “Asset still in memory” kind of error and just force delete, and luckily, it didn’t crash, but I then exited and restarted the editor just to be sure.

Completing the Import into Unreal, Option 2: Regenerating and retargetting the skeleton

  1. Select the FBX Import Options as follows:
    FBX Import Options 3
    FBX Import Options 4
  2. As you see, this option imports with no skeleton selected, so a new one is generated from the rig. Click Import All, and look at your new assets (e.g. SK_Mannequin2 and SK_Mannequin2_PhysicsAsset and SK_Mannequin2_Skeleton). Open these up and make sure they look right. You might have to set the materials appropriately on the mesh.
  3. You can optionally do a quick check now, optionally, to see if this character “accepts” the original mannequin skeleton. To do that, right click the mesh asset (e.g. SK_Mannequin2) and select Skeleton→Assign Skeleton, then select the original SK_Mannequin_Skeleton. Then follow steps 3, 4, and 5 of Option 1 to see if it works. If so, you can stop here, relieved you don’t have to go into the weeds below. If not, change the skeleton back to the generated skeleton (e.g. SK_Mannequin2_Skeleton).
  4. Now, let us set up retargeting for this skeleton. Open up the skeleton asset (e.g. SK_Mannequin2_Skeleton).
  5. In the toolbar, click the Retarget Manager icon which looks like a small man standing behind a larger man, and a curved arrow goes from the smaller man to the larger man’s head.
  6. In the Retarget Manager panel, click Add New Retarget Source, and in the popup, select the skeleton (e.g. SK_Mannequin2_Skeleton). Click some blank area to accept it.
  7. In the Setup Rig section, click the Select Rig selector and choose the Select Humanoid Rig option.
  8. In the list that opens up below, check that the source and target bones correspond correctly. They probably will. You can change anything that doesn’t match (e.g. if you deleted a bone or added a new bone to the rig in Blender, which can confuse the retargeter).
  9. Click the Show Advanced button above the list, and check that the advanced bone sources and targets correspond. Be sure to save the skeleton or later steps will fail. You have now set up retargeting for the new skeleton and can close the skeleton editor.
  10. You also have to set up retargeting for the original skeleton. Find it in Content/AnimStarterPack/UE4_Mannequin/Mesh/UE4_Mannequin_Skeleton and open it, then repeat steps 5, 6, 7, 8, and 9, except with this skeleton instead of the newly generated one. Be sure to save the skeleton or later steps will fail. You have now set up retargeting for the original skeleton and can close the skeleton editor.
  11. If you wish to use existing animations for the Mannequin, you now need to retarget them to the new skeleton. This is not necessary if you are creating your own animations in Blender. The next section shows how to do this. This next section is not necessary at all for Option 1 that uses the original mannequin skeleton.

Retargeting Animations from the Original Mannequin Skeleton to the New Skeleton Generated in Option 2 (Advanced Topic)

These steps are needed for Option 2, but not for Option 1.

  1. Navigate to Content/AnimStarterPack in the Content Browser of the Unreal Engine 4 Editor. We shall retarget all the animations. We cannot retarget blueprints or maps or folders so we skip Showcase (a map), and UE4ASP_Character (an actor blueprint) and UE4ASP_HeroTPP_AnimBlueprint (an animation blueprint) and the UE4_Mannequin folder. Select every asset in the folder but those four (one way to do this is click a blank area in the Content Browser to make it active, then type CTRL-A to select everything, then use CTRL-Click to deselect the four unwanted items). Right click on any one of the selected assets and select Retarget Anim Assets→Duplicate Anim Assets and Retarget. There will be a popup window.
  2. In the Select Skeleton popup, find your newly generated skeleton and select it. (if it is not there, try closing and restarting Unreal editor and start with step 1 again).
  3. You should see your new character appear in the rightmost box. If you didn’t change the pose of the bones, it should be posed just like the Mannequin in the leftmost box. If it is blank, it probably is OK since UE4 is stubborn about refreshing. Closing and restarting Unreal Editor should fix that.
  4. Click the Change button at the lower-right corner of the popup. Then select a directory for the new retargeted animations to go. You should probably create a new folder (right click an existing folder in the list and click New Folder and give it an appropriate name) for them rather than mix them with the old animations, which would be confusing. Click OK when you have the desired folder selected.
  5. Consider adding a prefix or suffix to the new names to make it easier to tell which is which in the future. I strongly recommend this.
  6. Click the “Retarget” button. It happens fast, couple of seconds.
  7. Navigate to the folder you selected for the new retargeted animations. In the menu bar, select File→Save All to save them all.
  8. Click to open a few animations and make sure they look right. (sometimes, depending on how much you changed the character from the original mannequin, it just can’t be made to work and you need to create your own animations in Blender.) If all is well, arms will not pull out of sockets, the head won’t be backward, legs will not be above the head, and so on.
  9. Advanced: I’m not going to walk you through this, it’s very involved—but you probably want to use this new character in a game or something. You would need to duplicate the UE4ASP_HeroTPP_AnimBlueprint, then edit it (very involved…it is complex with lots of parts) to replace the old skeleton with the new skeleton, the old animations with the new animations, etc. (I wish UE4 could retarget anim blueprints automatically!) Alternatively, start from scratch and write a new Anim Blueprint. Then, duplicate and edit the UE4ASP_Character blueprint to make it use the new anim blueprint and the new skeletal mesh character (this is much easier). Test the new UE4ASP_Character actor.

A Vagrant Data Science Virtual Ubuntu 18.04 Box

This post is not about game programming, but about setting up a Linux virtual box loaded with data science tools.  The repository can be found here on Github.  Below is from the README on Github for this box.

Quick Start

  1. Download the free VirtualBox virtual machine player.
  2. download and install the appropriate Vagrant package for your OS.
  3. Clone or unzip this repository somewhere. In this example, I assume you are on Windows and have put the files (including the Vagrantfile) in:D:\VagrantDataScience2018
  4. Open a command-line (recommended: Terminal on Mac, PowerShell or Git Bash on Windows, your favorite terminal on Linux)
  5. cd into this project’s root folder; In this example, if using Git Bash, you would type:cd \d\VagrantDataScience2018
  6. Check everything is gonna be alright so far by listing the directory. In Git Bash, that would be:ls -AF

and you should see something like:

$ ls -AF
.git/ bootstrap.sh*  howtos/  LICENSE  README.md  Vagrantfile

It is important that bootstrap.sh and Vagrantfile be there, as well as the howtos directory (or at least the README.md)

  1. Runvagrant up

in the terminal. This will take some time, a lot gets installed.

  1. If all goes well, you will see the howtos scroll by, and you can go to the machine by typing:vagrant ssh

Setting Up a Few Things

In your guest OS that you just ssh’d into using “vagrant ssh”, you can find the howtos in the directory:

/vagrant/howtos

These give you quick instructions for setting up the Kaggle app and accessing the guest OS’s web, RStudio, and Jupyter notebook in your Host OS’s web browser.

The howtos are reproduced here for convenience:

Kaggle HOWTO

Set up an account on kaggle.com, and in your profile, generate API key.

In Guest:

Place the key in ~/.kaggle/kaggle.json

chmod 600 ~/.kaggle/kaggle.json

kaggle -h

Jupyter Notebook HOWTO

In guest:

jupyter notebook --generate-config

jupyter notebook password

choose a password, can’t be blank

jupyter notebook --ip 0.0.0.0

open browser on host, browse to localhost:8888, type

in the password you set if asked

RStudio HOWTO

open browser on host, browse to localhost:8787

username: vagrant

password: vagrant

Web HOWTO

in guest, html files in /var/www/html

open browser on host, browse to localhost:8080

What’s Included

  • Tools: figlet and toilet: for printing banners to the terminal
  • web server: apache2
  • Build Tools: build-essential gfortran gcc-multilib g++-multilib libffi-dev libffi6 libffi6-dbg python-crypto python-mox3 python-pil python-ply libssl-dev zlib1g-dev libbz2-dev libexpat1-dev libbluetooth-dev libgdbm-dev dpkg-dev quilt autotools-dev libreadline-dev libtinfo-dev libncursesw5-dev tk-dev blt-dev libssl-dev zlib1g-dev libbz2-dev libexpat1-dev libbluetooth-dev libsqlite3-dev libgpm2 mime-support netbase net-tools bzip2 p7zip unrar-free npm
  • R and R Studio: r-base r-base-dev gdebi-core rstudio-server-1.1.453-amd64.deb: a statistics and data science scripting language
  • Java: openjdk-11-doc openjdk-11-jdk openjdk-11-jdk-headless openjdk-11-jre openjdk-11-jre-headless
  • Python: python3-pip python3-all python3-all-dev python-all python-all-dev python-pip ipython ipython-notebook
  • Octave: a free Matlab replacement
  • Python packages: awscli bigmler csvkit numpy scipy nose skll matplotlib pandas numexpr tables openpyxl xlsxwriter xlrd feedparser beautifulsoup4 plotly statsmodels dataset pymongo nltk networkx deap pydot2 rpy2 jug nose
  • Jupyter: jupyter-core jupyter-notebook: Python web-based data-science notebook
  • Kaggle: for interacting with kaggle.com data science page
  • cowsay: for the heck of it
  • xml2json-command: for data wrangling
  • Update: added Pandas to Python3 packages.  Don’t know why I forgot to do that before.

Deplorable Mountaineer

Keeping Your Git Repo Local

Introduction

Github is a good place to keep your remote Git repositories, especially if you want to share them.  However, if you want to keep it private, it costs extra.  Also, Github has a limit on the sizes of files it can store.  You can partly get around this with Git LFS, though that has some convenience costs and the free version has limits.  An alternative would be to have an external hard drive, perhaps one connected to your network, and keep your “remote” Git repo local.

My Setup: An Example Case

Personally, I have an external drive connected through the network to my Windows 10 PC, mapped as my Z: drive, and I use it as a backup drive.  It is also a good place to store remote Git repos.

I also use Atlassian’s Sourcetree for my Git repo management.  This is a GUI front-end to Git that makes working with Git convenient.  It also allows you to use an internal Git system so you do not need to install Git separately.  This system comes with Git Bash, a convenient BASH shell that is useful as a command shell separately from using Git.

Let us suppose I have a project called MyProject that already has some files in it, and I want to maintain a separate Git repo.  It is located in the directory D:\Documents\Reps\MyProject.  You can follow along with your own project if you change the paths and names appropriately.

Keeping your Git repo local with Sourcetree and Git Bash

Stage and Commit the project locally

  1. Open up Sourcetree.
  2. We first want to turn the project into a Git repo.  To do this, select from the top menu, the File menu, then select the item Clone/New.
  3. Press the Create button (with a Plus (+) sign icon on it).
  4. Uncheck “Create Repository on Account” since we are going to use a “local” remote.
  5. Either use the Browse button or just type, to set the repo path to D:\Documents\Repos\MyProject (or whatever it is for your situation).
  6. Click the blue Create button.
  7. You get a popup asking if you want to create the Git repo in a directory that already exists.  Yes, do this.  It will not overwrite your information (unless you have a directory or file called “.git” in the directory already).
  8. The “Working Copy” of your repo will appear.  If it doesn’t, select Working Copy from the left sidebar menu.
  9. Now, click the Stage All button, somewhere near the middle of the window, at the top-right of the Ustaged Files panel.  (You will only be able to do this if there are files in your project.   If not, you can add a test file just to try out these steps.)  The file(s) will move to the upper Staged Files panel.
  10. Type in some commit message in the commit box at the bottom (such as, “Initial Commit”).  Then press the Commit button at the bottom-left of the window.

Your project has now been committed, but only locally, that is within the newly-created .git directory in your project directory.

Create the Remote on your Disk Drive

Now, we get to the real point of this post: creating the remote repository on your disk drive.  My setup is that the external networked hard drive is the Z drive, and I want to put the remote in a file called Z:\Repos\MyProject.  As before, change this according to your actual situation.

  1. While still in Sourcetree with the Working Copy of MyProject still showing, click the Terminal button near the top-right of the window.
  2. In the Git Bash terminal window that appears (which should automatically have a working directory of /d/Documents/Repos/MyProject, or whatever your project working directory is), type the following to create the new repo (changing path and project name to what you need it to be):git init --bare /z/repos/MyProject

    Note, git bash uses /z/ instead of Z:\ for the root of the Z drive, and the directory slashes go forward instead of backward.  This can be fast or slow depending on how fast your drive is.  If all goes well, you will see a response like “Initialized empty Git repository in Z:/repos/MyProject/”.

  3. While still in the Git Bash terminal window, type the following to clone your project to that new repo you created (while you are still in the same working directory):git clone --bare /z/repos/MyProject

    If all goes well, you will see a message like “Cloning into bare repository ‘MyProject.git’…”.  It is ok if you get a message like “warning: You appear to have cloned an empty repository.”, because we still need to “push” the last commit to this remote repo.

Connect and Push the Local to the Remote

  1. In Sourcetree, select the Repository menu from the top menu and select the “Add Remote…” item.
  2. In the popup, with the Remotes tab active, click the Add button
  3. For Remote name: check the Default Remote.
  4. For Url/Path, type/z/repos/MyProject

    (or the one that you used above)

  5. Ignore the Optional Extended Integration section
  6. Click OK, then click OK again.
  7. As a test, click Push to push your last commit (make a new commit first if you need to). Check the “Push?” checkbox, and leave local and remote branches as Master, and leave “Track?” checked.
  8. Click the Push button at the bottom.
  9. Depending on amount to push and speed of the disk drive you push to, it might take a while. (My Z drive is slow, being an external networked drive)
  10. It should finish with no errors: no news is good news!

Conclusion

You now know how to keep a git repo local.  I considered showing how to set up a Gitlab instance in a virtual machine, but that was quite involved, and there are some difficult issues with using networked drives and Gitlab.