Documentation

Set Up Git

Now that your development environment is ready to go, we need to get the code and set up a CollectionBuilder project.

  1. Create a Repository
  2. Clone Your New Repository
  3. Committing and Pushing Your Files
  4. Generating Your Site
  5. Editing Your Repository

1. Create a New Repository

First, set up a repository on GitHub for your CollectionBuilder project. Each repository on GitHub is basically a folder for storing and tracking the code for a project.

  1. Login on GitHub
  2. Go to the repository corresponding to the type you are using:
  3. Click the green “Use This Template” button.
  4. This brings you to a “Create a new repository” form. Follow these steps:
    • Enter your new repository name. Use a lowercase name without spaces or odd characters. We often append _source or _draft to our projects to keep track of the status. If you are using GH, this name will become part of your site URL, so think through how it will look as a link.
    • Most users should choose “Public” repository. If you are hosting on GitHub Pages it must be public unless you upgrade to a paid account.
    • Leave the “Include all branches” option Unchecked! (you do not want all branches, only the main/master branch)
    • Click on the green button “Create repository from template.” This will take you to your new repository.

For GH users The rest of the instructions on this page are optional for you. You can move on to the metadata section. GH was designed so that all the edits can be made through the GitHub web interface.
If you’d like to work on your repository on your local computer, and you’ve installed all the software required), you can follow the steps below and work in the same way as the other types.

2. Clone Your New Repository to Your Local Machine

Now that you have a repository set up on GitHub, we need to copy that folder down to your local machine. Cloning the repository ensures the local version on your laptop is automatically configured to be connected to the version on GitHub.

  1. On your new repository page, click on the green button in the upper right labeled “Code”
  2. In the box that pops up, click on the button labeled “Open in Desktop.”
    • This action will automatically open GitHub Desktop for you.
    • GitHub Desktop will ask you to confirm the path of the repository you are cloning to your computer. In most cases, the path that it suggests is fine to use so you can just click on the blue “Clone” button.

GitHub Desktop clones your repository by downloading a complete copy of the code and history from GitHub and storing it in a folder on your computer. It is important to realize that the repository really is just a folder of files! You can open, move, or edit it just like any other folder on your computer.

Now, in the top bar of GitHub Desktop you should see three buttons. On the left, the “Current repository” button lists the repository you just cloned. In the middle, you can check your current branch (it should say main or master), and on the right there is a button that allows you to “Fetch origin,” “Pull origin,” or “Push origin.” As you work, this button allows you to sync the local version of your repository with the version on GitHub, and push and pull changes between them.

3. Commit Your First File

Open the _config.yml folder in your text editor. Change the “title” variable, and save the change. Now go back to GitHub Desktop to commit that change following the instructions below.

Commit to your change!

On GitHub Desktop, below the the column that lists your change to _config.yml, you’ll see a text-entry box labeled “Summary (required).”

  • Type a “commit” message into the box – a short message describing the changes you’ve made. In this case, you might enter something like “changed title of collection site.”
  • When you’ve finished your commit message, click on the blue button toward the bottom of the column that says “Commit to main/master.”
  • The “Changes” disappear, you’ve just made a Git Commit!

Now you need to Push!!!

You’ve committed your changes locally, but haven’t pushed them to the online repository yet. To push your commit up to GitHub, click on the button at the top right of the GitHub desktop screen that says “Push changes.”

  • Click “Push changes”
  • Navigate to your repository on GitHub web interface (On windows you can use the keyboard shortcut Ctrl + SHIFT + G in GitHub Desktop). You’ll see that the _config.yml file has been updated with the new changes.
  • Congratulations, you’ve pushed your first commit to GitHub!

4. Generating Your Site on a Test Server

Let’s test the new code.

Open the repository folder in your chosen text editor. Editors like VS Code or Atom open the full repository folder making it easier work on the files as a group and provide tools such as an integrated terminal. (GitHub Desktop has a short cut “Open in text editor” available in the top bar)

  1. If the terminal section of VSCode is not open, use the keyboard shortcut Ctrl + ` (control + backtick “ ` “, the key left of “1” shared with “~”) to open it. Or click the View menu at the top of VS Code and scroll down to “Terminal.”
  2. The first time you use this project folder on this computer, type the command: bundle install. Bundler will check the project’s “Gemfile”, install any missing dependencies, and create a “Gemfile.lock” listing the exact Gems set up for this project. You will see a bunch of output in your terminal window and if this is the first time bundling it may take awhile to finish. Once complete your terminal prompt will return.
  3. Next, in the terminal, type the command bundle exec jekyll s and press enter. This “jekyll serve” command will generate the site for you on a local server on your computer.
  4. In the terminal you’ll see some text appear, including a URL that appears after the title “Server address:”
  5. Hold down Ctrl and click this link to open the site in your browser (or copy the URL and paste into a private window).
  6. The generated site will be the demo version of CollectionBuilder. We’ll show you soon how to add your own content soon!
  7. When you’re ready to end your jekyll session, simply type Ctrl + C into the terminal. This stops the server from running.

5. Editing Your Repository

Once you start customizing your repository, here are a few things you should know:

  1. GitHub Destkop and your text editor (probably VSCode or Atom) are looking at the same folder of files (your repository), so once you save the changes you make to files in your text editor, those changes will show up in the left-hand “Changes” column in GitHub Desktop.
    • When you’re ready to commit the changes you’ve made, simply navigate to GitHub Desktop and select the checkboxes next to the files you’d like to commit.
    • Enter your commit message in the box at the bottom of the column, click the blue “Commit to main/master” button, and push your changes using the button in the top right of the GitHub Desktop window.
  2. If you’re working on multiple computers or collaborating, be sure to fetch and pull changes before you push new ones.
    • You can do this by clicking on the button in the top right of the GitHub Desktop interface labeled “Fetch origin.”
    • If there is content to pull, once it is fetched this button will say “Pull origin.” Click on the button to pull the changes, and you will see your local repository change accordingly.
« Install Software Back to Top Metadata »