MUDDLE from Command Line

Step One: Create a GitHub Account
Before you can start MUDDLING, you'll need to create a GitHub Account. If you've never worked with Git or GitHub before, here's a great video to help get you started: Get Going with Git.

Step Two: Download Git on your Local Machine
Once you've created your GitHub Account, you will need to download Git on your local device. This is how you will tell your computer to track the files you share between your local device, the MUDDLE Sandbox, and the master MUDDLE repository. To download Git on your device, go to Git Downloads and select your operating system (i.e. Windows, Mac OS X, or Linux/Unix). Follow the setup instructions and confirm that Git is installed by opening the command line window on your local device. Before you can begin committing files, you will need to link your Git terminal to your GitHub account. Detailed instructions on how to do this are provided in the Get Going with Git tutorial video.

Step Three: Fork MUDDLE repo on GitHub
Next, you will need to Fork the master MUDDLE repository. The option to Fork is located on the top right of the master MUDDLE repository page on GitHub. Once you hit Fork, you will see a page that looks like this:

Once you've forked your copy of the master MUDDLE repository, you will see it listed among the others in "Your Repositories" on GitHub.

Step Four: Clone Forked MUDDLE repo to Local Machine
Next, you will need to clone your forked MUDDLE repo to your local device. To do this, select "Clone or download" (in green) from the options located just above the repo files, then copy the offered URL. Now, it is very important to know where you are in your local directories before you clone a cloud repository onto your computer. Once you have your command line open, you will need to select the directory/folder you wish to clone the MUDDLE repository to. A good way to set this up is to create a new folder on your Desktop or in Documents specifically for your cloned GitHub Repositories. To move between folders at the command line, you will use the command "cd" and type the name of the folder you wish to clone to (for example cd Desktop/GIT_REPOS or cd Documents/GitHub). If you have stepped down too far into a folder and wish to go back to the parent directory, use "cd .." to go back one directory level.

Once you clone the forked MUDDLE repo, a new MUDDLE folder will appear in your GIT_REPOS or GitHub directory.

To clone, use this command and paste the URL you copied in place of "[URL]":
git clone [URL]

Once you do this, you will see that that a copy of all the existing files from your forked MUDDLE repo are now listed in your local directory.

Step Five: Create upstream to MUDDLE repo on Local Machine
Ok, now that you've cloned your MUDDLE repo at the command line, it's time to create the upstream from which the MUDDLE community's changes and version history derives. Every time you want to commit changes to your files on your local branch, you will need to pull in the changes from the MUDDLE Upstream; we'll discuss this in more detail later. For now, enter this command in your terminal:

git remote add upstream https://github.com/taylorcate/MUDDLE.git
Then to verify you have correctly set the URL for upstream use this command:
git remote -v

Once you've created your upstream, check your status by entering the command, git status. You should see a message that says "Your branch is up to date with 'origin/master'". This is how you'll know you're ready to begin saving work to your local directory.

Step Six: Save Work to Sandbox using House File Naming Conventions
Now we are going to go over adding and committing files from your local computer to your online FORKED MUDDLE repo. First, you will need to open your MUDDLE folder and navigate to the "Sandbox" folder. Then, add an author/artist folder following the House File Naming Conventions. For each work (i.e. poem, graphic, etc.) you will create a new folder within that larger author/artist directory. Once you've moved all your files into the appropriate folders, you must "add" and "commit" them at the command line in order for your changes in your local branch to take effect in the public repository.

Step Seven: Add and Commit changes via Command Line / Git Bash

WARNING! Always be sure to "pull" both from your remote (or "online") FORKED repo and upstream before you "add" or "commit" changes in your local directory. Why is this important? When you enter the following commands, you make sure your cloned MUDDLE repo, on your computer, takes in all the changes other users made to the their cloned MUDDLE repos (that have been accepted into the group sandbox by MUDDLE editors) while you were working on your projects, as well as any changes you might have made directly to your FORKED repo using GitHub's online interface. By pulling before you commit, you prevent what is known as a "merge conflict." More info on "merge conflicts" can be found on our Troubleshooting page (link coming soon).

Enter these command in your terminal:

To pull any changes you made online in your FORKED repo:
git pull
Then, to pull any changes accepted into the main (upstream) MUDDLE repo:
git pull upstream master

Now that you've "pulled" you can "add" and "commit" your changes. At the command line, enter git add -A; this will "stage" all the files you changed for you to approve before committing those changes to the cloud (online, remote FORKED repo.) After adding, we suggest checking your status (git status)—you should receive a message that says:

Your branch is up to date with the 'origin/master'
Changes to be committed:

Then it will list the files that have been changed. Next, you will enter the command git commit -m "Commit Message" making sure to add a detailed commit message so you can look at the history and understand your decisions to commit your files at these particular moments. Once you enter the commit, check your status again. You should see a message that says:

Your branch is ahead of 'origin/master' by # commits

Once you see that message, all you have to do is enter git push and your changes will be sent to your online FORKED repository.

You will see the items you added appear in the "Sandbox" folder in your Forked MUDDLE repo on GitHub.

Step Eight: Create a pull request on GitHub from your Forked MUDDLE repo to the main MUDDLE repo
Next, you will merge your changes with the master MUDDLE repo by selecting "New pull request." Select "Create pull request."

Once we see you've made a "pull request" we will accept it and merge the changes from your FORK into the main MUDDLE repo.

Step Nine: Pull Upstream
We're almost there! Next (back in your command prompt), "cd" to your MUDDLE folder and "pull" changes from the master MUDDLE repo into your local branch using the command git pull upstream master. In your Git terminal, you'll see a breakdown of what changed since you last pulled.

Step Ten: Sync Up the Repos
Next, check your status—you should receive a message that says,

Your branch is ahead of 'origin/master' by # commits

Then, enter git push to send those changes to your online, FORKED repo.

Congratulations! You are officially a MUDDLER.