Never done anything with git in your life? Don't worry about it! Follow this step by step guide to get your environment set up and ready to make some puzzles. This guide will cover software installation, git commands, and testing guidelines. If you need help turning your puzzle content into valid HTML, head over to our webification guide.

Git is what we use to push all the files from your local machine into our Github repository (repo). Github IS A COMPLETELY DIFFERENT THING than git. Github is the website you're currently on and reading this. Git is a program you will download from this website. The default download should be fine, as well as all the default options during installation.

If you're worried about using VIM as your default editor and have another program like Notepad++ already installed, you can switch your editor when you encounter this option:


The only time you'll ever need to use the editor from within Git is when dealing with merge PRs, but if you only plan on using Git for webification, then the way we use it means you won't need to do any merges and thus should never need to worry about this.

This is technically optional, but is very highly recommended because it makes working with PuzzleJS much easier than the alternative, which is applying a command-line flag to your browser. Visual Studio Code, or VS Code, is available to download from the Microsoft Store, or from here. Again, the default download and install options should be fine, including any agreements you may need to accept the first time you open VS Code.

1. Opened VS Code --> click the boxes icon in the sidebar to open up the Extensions pane:
   
   
2. Search for "Live Preview", and then on its page, click the blue Install button. Once it's installed, it'll change to say Uninstall:
   
   
3. Set the extension to open pages in your browser. Next to the install button, click the gear icon, then extension settings:
   
   
4. On the settings page, change the "Open Preview Target" option to "External Browser":
   
   

1. In this example, let's say this is a private repo located at https://github.com/jbodner09/pd2024-webification. You'll first need the repo's owner to add you as a contributor. Talk to them, and once they've sent the invite, you'll either get an email, or just go directly to that repo in your browser, and it will ask you to confirm that you want to be a contributor. If you don't know who owns the puzzles, ask around.
2. Once you're a contributor, you'll be allowed to clone the repo. To do that, look for the green Code button, and click it to open the dropdown. In the dropdown, the default clone method of HTTPS should already be selected, so look for a button to the right of the URL that says "Copy url to clipboard" when you hover over it. Click it to copy the url, which you'll need in the next steps.
   
   
3. Open a Terminal session (on Windows 11) or a command prompt (on Windows 10). If you're on Windows 11 and Terminal isn't installed, you can get it from the Microsoft Store, or you can just use a command prompt. The easiest way to open a command prompt is to hit the Windows Key + R to open the Run dialog, and then type "cmd":
   
   Once you're in the command prompt, navigate to the folder you want your clone to live in using the "cd" command. You can go directly to any folder from anywhere else by typing its full name, for example cd C:\Users\Josh\Repos. Note that if any folder in the path contains spaces, you'll need to wrap the entire path in "quotes", like cd "C:\Users\Josh\Software Projects". If you want to create a new folder to contain the repo, you can create it in Windows Explorer first, and then just navigate to it in the command prompt.
4. Clone the repo by typing git clone <repo url>, where the repo url is what you copied in Step 6. In this case, that would be git clone https://github.com/jbodner09/pd2024-webification.git. Note that to paste into the command prompt, just right-click; a keyboard shortcut like ctrl+P likely won't work. Once the repo is cloned, don't forget to "cd" into it before doing anything else!!! This is because it will be cloned into a new folder inside the folder your command prompt is currently in.
5. At this point or any of the future git steps, git may ask you to log into Github. The easiest way to do this is by choosing the option to log in using the browser, as that will open a regular webpage you can type your Github credentials into. If you've got 2-factor authentication set up on your Github account, it may be a little trickier, as you might need to use a Personal Access Token instead. If that's the case, follow the instructions in this article.
6. Now that you have the files locally, let's assume you want to create a new puzzle. The proper way to do this is to create a new branch in git to do all your work in.
   • First, make sure your command prompt is currently at the base level of the repo folder that was just created. This doesn't happen automatically after you clone, so you'll need to "cd" into it. You'll know you're at the root level if you do a "dir" command and see a file called ".gitignore".
   • Next, to make sure you're up to date with the latest changes from everybody else, type git pull. Since you just cloned, you'll already be up to date, but it's very important to do this periodically, especially before you start making big changes. This will ensure you don't need to do any work later to merge other peoples' work into yours. This is also a good way to confirm you're in the correct folder in the command prompt, since you'll get an error message like "fatal: not a git repository" if you're not.
   • At this point, or one of the future steps, git may also complain that it needs you to run a couple of git config commands. If it does, just type the commands it gives you, which are likely just setting what user and email is currently making changes.
7. To make a new branch, first make sure you're currently on the main branch. To do this, type git branch. The current branch will be starred and highlighted:
   
   
   If you're NOT on the main branch, type git checkout main, and then don't forget to pull as well. Then, to create your new branch, type git checkout -b <branch name>.

• The branch name can be anything, but it's good practice to use one branch per puzzle, and to also put your name in the branch name so people can easily find their own branches. For example, you could do git checkout -b users/joshbo/ebay for a puzzle named "ebay" and a user named "joshbo".
• Note that the branch name has nothing to do with the files inside it automatically, and it's just good practice to name your branch after the work you're doing. Git is just a system for tracking work, so if you want files inside your branch with a certain name, you have to create those files in Windows Explorer or another program.

12. Immediately push your new branch by typing git push so that the online repo is aware of it. The first time you do this, you will see an error message:
    
    
    Copy and run the exact command it gives you (git push --set-upstream origin <branch name>). You'll only need to do this once per branch you create; every other time, you can just do a regular git push. To copy text from the command prompt, highlight it, then right-click to copy what's highlighted.
13. Now, you're ready to start editing files. Please note: don't ever edit anything UNLESS you're currently in your own branch. If you want to go to another machine and check out a local copy of a branch you've already pushed, you can just do git checkout <branch name>.
14. In VS Code, click the top button in the sidebar to open the Explorer pane. It should say that no folder is opened if this is your first time doing anything:
    
    
    Click the Open Folder button and find the folder that you cloned the repo into. Don't go INTO the folder; just highlight it in the main part of the window (not the left bar, if you have a left bar with a list of folders) and click "Add":
    
    
    VS Code may ask if you trust the authors of the files, which you can say Yes to. The next time you open VS Code, it should remember where it was, but if it doesn't, make sure you always have this folder open in your workspace since it's what lets the extension you installed work properly due to the way we've set up our resources.
15. Now that you've got your list of files available in VS Code, you can just double click anything from there to open it:
    
    
    If you're creating a new puzzle, make sure you copy an example to get started with and rename the copy; don't ever make edits to existing files that aren't yours since somebody else may also be working on them!

• To make a copy of a file, you can just do that the way you usually do in Windows Explorer, and VS Code will automatically see the new files.
• If the repo has been set up using our other wiki pages, there will likely be a clearly marked "example-puzzle" folder for you to copy and rename to your puzzle's name, as well as clear instructions in the file for where to add your changes.
• The repo that contains the puzzles may also contain a README file (which is also displayed on the website for the repo) with abbreviated instructions for adding a puzzle. Otherwise, full webification instructions are available here. You'll probably want to read that page if you're not sure how exactly to turn your puzzle content into a functional webpage.

16. Once you've made some changes, you'll want to see what they look like. The extension we installed added a little button in the top right corner of VS Code to Show Preview:
    
    
    Clicking this will open up a browser window to whatever file is currently open/active. Note that this must be an HTML file. Even cooler though, you can make edits in VS Code while the preview is still open, and the preview will update automatically!

• Don't forget that you must also manually save your files; the preview will show you what you just typed even if you haven't saved, but for git to pick up the changes, they must be saved properly.
• VS Code won't make a big deal about telling you that it actually saved the files, so if you need confirmation, remember that you can always check in Windows Explorer by right-clicking and viewing the file's properties to ensure that the last time it was modified matches when you saved.

17. To see what changes git is aware of since the last time you pushed something to the server, you can type git status. It will also show a message saying that if you want to accept those changes, you need to add those changed files to the list of files to push:
    
    
    Note that this message may be different for newly-created files than for existing files that have just been edited.
18. Once you've made a sufficient amount of progress, you should push your changes to the server. Note that this DOES NOT automatically merge anything in; it will still live only in your branch. This is important for making sure you don't lose work though, especially if you do work from multiple machines.

• Assuming you've only changed your own files, you can easily add them all by just typing git add --all (note the two dashes).
• Otherwise, you can add individual files by typing git add <filename>, where the filename is the exact name (including the path) shown with git status.
• If you accidentally changed a file you didn't mean to, you can also follow the instruction in git status to restore any file.
• Once you've added the files, type git commit -m "commit message", where the commit message summarizes what you changed (the quotes are required).
• Then, do a git push. This is the standard 3-step process to sync your local changes with the server: add, commit, push.

19. Once you're done making changes, it's time to open a pull request so your changes can be merged into main. Note that this doesn't mean you CAN'T make any more changes though; pushing changes to a branch that has an open pull request will automatically add those changes to the pull request. Back on the repo website you were at in Step 5, if you're lucky, Github will recognize that you've made changes and will offer a button to open a pull request:
    
    
    Otherwise, you'll need to either switch to your branch from the dropdown:
    
    
    And then click the "Contribute" dropdown to surface the button to open a Pull Request:
    
    
    Or go to the list of all branches and click the ... menu for yours:
    
    
    
20. Once you've got an appropriate title and description, open your pull request and let the repo owner know you're ready for it to be reviewed. PLEASE DO NOT MERGE YOUR OWN PULL REQUESTS. The owner may want you to make changes first, and they will also be on the lookout for any merge conflicts, although those should be unlikely unless you're actively working on the same files as somebody else.

• At any point, you can push new changes into this branch, and the pull request will be updated automatically. If somebody requests changes, you can also resolve too.
• Once your puzzle is merged into main, don't forget to checkout main and git pull to update your own main branch! Or if you made changes to your own branch on another machine, you can git pull those changes to your local copy of the branch on any other machines too once you've checked out that branch.
• After the pull request is merged, if you want to make any future changes, you can still use your old branch, but you'll need to open a new pull request. If the changes you're making aren't related to the work you were previously doing in that branch, it would probably be better to instead create a new branch.
• You can also use git merge to merge changes from main into your branch at any time, but just beware that if you've done work in your branch after your pull request is merged, the two versions of that puzzle in the two branches will likely create a merge conflict!

As for actually making your puzzle, besides filling out the parts of the template that you need to, you can follow the webification guide that you likely came here from to learn how to do more than just copying and pasting. And if you're using PuzzleJS, don't forget to scroll down to the bottom of its online documentation to find the pages that list all the possible options you can use and ways to override the default styling.