Atlas + Git
While we've designed Atlas to do everything you need to write, edit, and build your projects, there may be cases in which you want to work outside of the UI. If you want to work with your favorite local text editor or just want to access Git's powerful tools directly, you can clone your project's repository from Atlas. First, you'll need to pair your SSH public key with Atlas.
Creating Your Key
If you're using Windows, please install git locally using the msysGit project. This will give you access to a command environment called Git Bash and will also allow you to use the ssh-keygen program mentioned below.
First, check for an existing key by opening up Terminal/Git Bash and entering:
$ cat ~/.ssh/id_rsa.pub
If you get output, it should be a long string that starts with "ssh-" and ends with your email address. This is your public key. Copy the whole string, and skip to the next section.
You'll be asked for your passphrase for this key in a following step; if you don't remember it, proceed with creating a new one.
- If you get "No such file or directory" (or see a string with no email address), you can generate a new key by following these steps:
- In Terminal/Git Bash, type:
ssh-keygen -t rsa -C "firstname.lastname@example.org". Make sure to fill in the email address that you use with Atlas.
- At the prompt to "Enter file in which to save the key (/Users/you/.ssh/id_rsa)", just press return.
- Enter a passphrase. You'll need to do this twice.
- In Terminal/Git Bash, type:
You should see output indicating that your key has been created. At this point you can run this command again:
$ cat ~/.ssh/id_rsa.pub
Now you should see a string that starts with "ssh-" and ends with your email address. Copy that string.
Adding Your Key to Atlas
In Atlas, click your username next to the gear icon at the top right to get to the Account Settings page. Then click the SSH tab.
Under "Add an SSH Key," add some descriptive title (e.g., "local machine"), and then paste the string you copied previously under "Public Key."
Click the "Add Key" button, and that's it! You should now have the ability to clone down Atlas repos and work with files locally.
Once you've added your SSH public key to Atlas, you're ready to start using Git to work with your project.
You can download git from the git-scm site. Just follow the instructions for your platform.
Clone Your Project from Atlas
- Go to the Project Settings page and copy the Git URL from the box on the right.
- From the command line, use
git clone <your_URL>to pull down your project's repository. By default, using this command will pull the repo into a directory named by your project name. You can override this by putting a new directory name at the end of the command.
- You'll be prompted for your SSH key passphrase; enter the passphrase you chose when you created your SSH key.
Now you can open and edit your files in your favorite text editor or use Git's command-line tools to modify them directly.
Pushing Edited Files Back to Atlas
Once you've made your edits, you'll need to add any new files to be tracked by Git, commit your changes, and then push back to Atlas:
- Add any new files so that Git can start tracking them. Use
git add <filename>to add an individual file. Use
git add .to add all files in the current directory and all subdirectories.
- Commit the changes using
git commit -a -m'commit message'. Try to use the commit message to leave yourself a note about what you were doing. For example, if you were just adding a big section on the foo method, you'd add a message like "Added section covering foo."
- Push the changes back up to Atlas using
git push origin master.
My Push to Atlas Keeps Getting Rejected
If you're getting a message that your changes are rejected, it's most likely because someone has changed the files on Atlas since you started working locally. To fix this, you'll need to commit your current changes and then use
git pull origin master to pull in the changes from Atlas. Once you've synced the changes, you'll be able to push your work back up.
Getting a Diff
You can use Git to get a diff between the files in your local checkout and the files on Atlas. To do this, use
$ git fetch origin Password: remote: Counting objects: 5, done. remote: Compressing objects: 100% (3/3), done. remote: Total 3 (delta 2), reused 0 (delta 0) Unpacking objects: 100% (3/3), done. From https://atlas-admin.oreilly.com/git/1230000000065 92d4f99..e9fbbe2 master -> origin/masterThis fetches the changes into a local branch, but does not merge them in automatically.
Once you've fetched, you can use this command to see the files that have changed between your local copy and the remote copy:
$ git diff --name-only master..origin/master
This command will just give you the list of files. If you want to see the actual differences, just leave off the
--name-only flag. Once you're satisfied that nothing nefarious is in there, you can merge in the changes you just fetched using this command:
$ git merge origin/master
If you'd like to work with your files locally but don't want to use Git, you can download all of your project's files in either zip or tar.gz formats. Navigate to your project Settings page, and click on the format you'd like.
Once you've made changes, you can load updated files back to Atlas by simply dragging and dropping them into the files list on the project Dashboard or the files pane in the Editor.
Git Quick Reference
Here are some of the key terms you'll need to understand to use git:
- Local repository
- A git repository that is on your local drive. You can make any changes you want to this copy without affecting other files.
- A named version set of files within a Git repository. The default name is "master."
- Remote repository
- A named link to a Git repository on another machine. You can have as many remote repositories as you want. "Origin" is the default name, but you can choose any name you like when you add new "remotes" (links to other repositories on different servers).
- Push and pull
- Git lingo for sending the changes made in a local repository to a remote repository, or vice versa.
- Downloading a remote Git repository onto your own machine so that you can edit it locally.
- A commit saves all your changes under version control.
The following table summarizes some commonly used commands.
||Creates a new blank repo|
||Commits changes to the repo|
||Returns the commit status of the current repo|
||Adds all files to the repo|
||Adds a remote repository to which you can push or pull changes|
||Lists the remotes in your repo|
||Pushes changes from the specified local branch specified to a remote repo. We’ll mostly use
If you want to know more about Git and all the things you can do with it, check out these resources:
- Git Cheat Sheet. A great reference to the key commands.
- Git for Designers. A nice introduction to git for non-programmers.
- Pro Git. The online version of Scott Chacon's excellent book, Pro Git.
- O'Reilly Webcast: Git in One Hour. A nice video from Scott Chacon that introduces all the key parts of using Git.
Syncing GitHub and Atlas
Because book files in Atlas are managed with Git, you can easily sync those files with a repository on GitHub.
To sync an Atlas project with GitHub, first create a new repository. You'll be prompted to enter a name, a description, and whether you want to make the repo public or private (available only if you have a paid account). We recommend giving the project the same name in Atlas and on GitHub.
Once you create a project, you'll see a screen that lists some helpful commands for what you'll do next. Locate the "Existing Git Repo?" section and then find the line that looks like this:
Once you've got the line, copy the repo's url (in our example, it's email@example.com:MakerPress/new_project.git) and enter the following command in the directory where your local Atlas repo is stored. (Note that the word "origin" is the only thing we're changing from the original command.):
$ git remote add github firstname.lastname@example.org:MakerPress/new_project.git
Once you've set up the new remote, you can push to it with this command:
$ git push github master
You can then take full advantage of all the features and community available on GitHub.
Conversely, if you already have a repo on GitHub that you’d like to pull into Atlas, all you have to do is clone it down and add a new remote to an Atlas repo, like this:
$ git clone email@example.com:MakerPress/new_project.git Cloning into new_project... warning: You appear to have cloned an empty repository. admins-MacBook-Air-2:Desktop odewahn $ cd new_project/ admins-MacBook-Air-2:new_project odewahn $ git remote add atlas firstname.lastname@example.org:odewahnoreilly/new_project.git