the Sim Settlements forums!

Register a free account today to become a member! Once signed in, you'll be able to participate on this site by adding your own topics and posts, as well as connect with other members through your own private inbox!

Tutorial Using Git for mod version control

Whisper

Well-Known Member
Patreon Supporter
Community Rockstar
Verified Builder
Vault Librarian
Messages
1,320
Relax

Take your time with this. We aren't jumping in at the deep end. It's the simple stuff first, building up in stages as you use GIT and get to creating mods. Mostly focusing on Sim Settlements plots.

Some of this is simple strategy - when to take a copy of your mod, how to add it to your mod repository, how to get a particular version back when you need it. Making copies on a USB drive or external hard drive. Lots of copies keep stuff safe and you never know when your computer is going to get zapped by the gremlins of hell.

Installing Git

Here is the download page for Git on Windows:

https://git-scm.com/download/win

Grab the Windows 64-bit version.

It's also worth grabbing the free e-book, though if you're new don't bother reading it yet - that's for more hardcore users. Give it a few months before you dig into it though (you'll intimidate yourself if you jump into that).

https://git-scm.com/book/en/v2

Easy Options

Choose the base install using the bash shell, don’t integrate it into the command window, and use Unix checkin and Windows checkout. Ask in the modders channel or do a google search if you’re feeling stuck.

Once it's installed...
 
Last edited:
Layout Strategy

You do *not* want to be using Git directly in your <FO4 Install>/Data/ directory. If you do you'll be adding every piece of base game and DLC and mods you've downloaded to your repository. Gigabytes worth of stuff you don't need copies of.

Instead you create yourself a folder elsewhere. Preferably on a disk with some available space:
upload_2019-11-26_18-4-50.png
Simple, each subdirectory is an individual mod with it's own Git repository:
upload_2019-11-26_18-6-23.png
Note the faded folder called ".git" - to see this you will need to set up your folder views. You basically want to see file name extensions and hidden items - apply them to the folder - and then click the "Apply to Folders" button to make it Windows-wide (google for more information):
upload_2019-11-26_18-8-59.png
 
Overall Strategy

The general idea is to take a copy of whatever changes you make to your mod and put them into your custom area. Do it every time you complete a section (or milestone) of your mod.

In the case of a Sim Settlements plot mod, good times to take a copy are:

* completing a level (L0, L1, etc) of the plot
* completing a stage level (L0 S1, L0 S2, etc) of the plot
* completing clutter for a level
* completing a plot
* right before going to bed (and make a copy on a USB or external drive)

Lets start with turning your separate directory into what is called a "Git repository".
 
Making A Git Repository

In an empty folder right-click > Git Bash Here (trust me, the GUI sucks):
upload_2019-11-26_18-18-15.png
You get a command-prompt:
upload_2019-11-26_18-22-4.png
Yes, this is a version of Linux Bash for Windows. Don't worry about it, we're sticking with basic commands.

Setting Up

Setting up a Git repository, type in:
Code:
$ git status
fatal: not a git repository (or any of the parent directories): .git
This is Git saying "I have no idea". To turn it into a Git repository:
Code:
$ git init
Initialized empty Git repository in E:/FO4Modding/Fallout4/WhisperMods/Test/.git/
And now it shows the semi-translucent .git folder:
upload_2019-11-26_18-25-15.png
From now on, mod files that you put into this directory can be added to the Git repository.
 
Last edited:
Your First File

Once you've created your initial Sim Settlements mod (follow the tutorials in the Builder's Toolkit - save and name it appropriately - exit the Creation Kit) copy it from <FO4>/Data/ over to here:
upload_2019-11-26_18-29-23.png
Then type the following in the Git command line:
Code:
$ git status
On branch master

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        Whisper Power Plots.esp

nothing added to commit but untracked files present (use "git add" to track)
Adding It

To add it to the Git repository:
Code:
$ git add *.esp
Followed by:
Code:
$ git status
On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

        new file:   Whisper Power Plots.esp
Now we're going to save ("commit") it to the the Git repository:
Code:
$ git commit -am "Initial import of the empty 'Whisper Power Plots.esp' file into GIT"
[master (root-commit) 60d760d] Initial import of the empty 'Whisper Power Plots.esp' file into GIT
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 Whisper Power Plots.esp
Looking at it now:
upload_2019-11-26_18-43-4.png
This is Git saying "it's saved, nothing has changed since the last time".
 
Adding Changes

You've made a change to your mod (added L0 to a plot, for example) and copied it over:
upload_2019-11-26_18-56-0.png
Now you check the status of your Git repository:
upload_2019-11-26_18-56-42.png
Yes, you need to save. Here's what to do:
upload_2019-11-26_18-58-4.png
Comments

Note that I've put the comment as *exactly what I've changed*. You don't want War and Peace here, however "Added level L0" is useless. Added it to what? Be specific so you can look at it in 6 months time if you have to make changes.

Remember to do the same if you've deleted something from your plot - not just additions:
upload_2019-11-26_19-2-17.png
Be specific:
upload_2019-11-26_19-3-23.png
You can even get very specific, with shorthand that makes sense to you:
Code:
git commit -am "Del Ext Tesla Plot: L0: Looked too tacky
 

Attachments

  • upload_2019-11-26_18-58-18.png
    upload_2019-11-26_18-58-18.png
    3.9 KB · Views: 3
Last edited:
Adding More Files

So lets add the following to the repository (several files in a subdirectory):
upload_2019-11-26_19-10-31.png
Checking the status:
upload_2019-11-26_19-11-33.png
This is not yet in the repository. Lets add the files in the Meshes/ directory:
upload_2019-11-26_19-12-26.png
And see what we've actually added:
upload_2019-11-26_19-13-9.png
That's a lot of stuff! Now to save it:
upload_2019-11-26_19-14-28.png
And now it says "it's all saved":
upload_2019-11-26_19-14-58.png
 
Looking At History

Putting all this in your repository is all well and good - how the hell do you see what you did a week ago? There's a long-winded git command for that:
Code:
git log --graph --decorate --abbrev-commit
Which shows a multiline set of information for each save (commit) to the repository. Which I won't show because it shows too much of my setup information. A more abbreviated one is:
Code:
git log --graph --decorate --pretty=oneline --abbrev-commit --all
upload_2019-11-26_19-25-31.png
Now you can see what we've been doing. The yellow letters-and-numbers at the left is the individual commit-numbers. The "(HEAD -> master)" part says that this is where we are at present.

Making It Simpler

Since that is a long-winded command to remember, we need to set up Git so that we can do things shorter. We need to set up a "~/.gitconfig" file with an alias (shortcut command):
Code:
vi ~/.gitconfig
I'm assuming that you're at least semi-familiar with the "vi" editor. If not, use Notepad++ - you will find the file in:
upload_2019-11-26_19-30-47.png
You should put into it some stuff like this:
Code:
[user]
        email = whisper@whisperfakeemail.nz
        name = whisper

[alias]
        lol = log --graph --decorate --abbrev-commit
        lola = log --graph --decorate --pretty=oneline --abbrev-commit --all

[color]
        branch = auto
        diff = auto
        interactive = auto
        status = auto
[core]
        excludesFile = C:/Users/GGPC/.gitignore
The aliases are the two shortcuts we are setting up, so now I can use:
upload_2019-11-26_19-36-35.png
And I never have to remember that long command again.

I can even use the following to show only a short number of the latest entries:
upload_2019-11-26_19-37-48.png
 
Ignoring Files

You will note a couple of posts back that when we did a "git status" it only showed the "Meshes/" folder. It did not show the "Whisper Power Plots.7z" file.

This behavior is configured in the .gitignore file:
upload_2019-11-26_19-42-50.png
Which I have the contents set up for files I don't want to have added to my repositories:
Code:
# Projects #
############
nbproject/

# Executables #
###############
*.com
*.exe
*.scr

# Archives #
############
*.7z
*.dmb
*.gz
*.iso
*.jar
*.rar
*.tar
*.zip

# MySQL Dump Files #
####################
*.dmp

# Windows *.db (thumbs) files #
###############################
*.db
Most of this is because I do a bit of coding - all you're likely to worry about is the *.7z, *.rar, and *.zip files.
 
Old Versions

So you want to look at an old version. First make sure that there are no changes to be saved:
upload_2019-11-26_20-0-29.png
Do not forget to do this! It can cause issues for a new Git user - one that you'll have to go hunting on google for to get fixed.

Now you "check out" the version number that you are interested in:
upload_2019-11-26_19-56-27.png
This is what things look like now - note where the "(HEAD)" section is:
upload_2019-11-26_19-57-26.png
In Windows, the entire Meshes/ folder has disappeared (though the .7z file has not, since it is not being tracked by Git):
upload_2019-11-26_19-58-30.png
To go back to your original state (do this before copying over any changed files - again, you can cause yourself some major issues):
upload_2019-11-26_20-3-26.png
And your Meshes folder is back:
upload_2019-11-26_20-3-54.png
 
More Advanced

There are other commands available when you get more used to using Git. It will be a while before you find you need them - here's some starting information though. You can find more information in the Git book and via google search.

When you copied over a file that you realize you shouldn't have - before you commit any changes, you just want everything back the way it was:
Code:
git reset --hard HEAD

Committing a single file:
Code:
git commit -am "<message>" path/to/filename

Un-staging a commit (too many files were added with "git add *") - to reset and start again (this resets the entire commit, without altering the files):
Code:
git reset

Change a comment that you typo'd, didn't make clear enough, etc. If it hasn't been pushed to a git server (brings the comment up in vi to be changed):
Code:
git commit --amend

Branches

This is a way of creating a test-bed area of your existing mod, while keeping your original mod files untouched. You create a "branch" of your mod.

To create a new branch for testing:
Code:
git checkout -b testing
upload_2019-11-26_20-14-2.png
You can see that HEAD is now pointing to the "testing" branch rather than the "master" branch:
upload_2019-11-26_20-14-43.png

You can make whatever check-ins that you want to your testing branch. To go back to your master branch:
upload_2019-11-26_20-15-41.png
upload_2019-11-26_20-16-2.png

To see all branches in your Git repository:
upload_2019-11-26_20-17-1.png

You can merge the two by being in the master branch and using:
Code:
git merge testing

Or you can simply drop the testing branch entirely, deleting it as if it were never there (you need to be in your master branch):
Code:
git branch -d testing

Note that you can never delete your master branch. That is the master!
 
Top