Skip to content

Latest commit

 

History

History
128 lines (96 loc) · 5.76 KB

gsg_editing_locally.asciidoc

File metadata and controls

128 lines (96 loc) · 5.76 KB
Raw

Editing locally (without the wiki)

One of the cool things about the Gollum wiki is that it’s basically just a plain interface on top of a git repository. This allows a lot of flexibility in using the tool. For example, suppose you have a long flight and want to edit on the plane. No problem — just pull down your changes, do your edits, and then push them back up when you land. Or, suppose you’d rather just skip the wiki interface entirely and just do everything locally. That’s fine to — you can just do your edits, but you can push your project to the editing environment to share it with tech reviewers or access O’Reilly’s build systems (more on that in a bit).

There are a couple of things you’ll need to be able to edit locally:

  • A copy of git installed on your local machine. You can get git at [link to git]

  • Your public key. This should have been installed when the repo was set up, but if not, contact [???]. (Someday we hope to have a UI where you can do this yourself, but that’s for the future.)

Once you’ve git this set up, you’re ready to use git. There are a few caveats. The first is that Gollum can only work on the master branch, so any changes you want to share will need to be committed to the master and pushed up. The second is that is anyone else makes changes on the repo in the interim, you’ll need to resolve any conflicts to merge their changes; git will warn you about this when you try to push up the new repo. Describing conflict resolution is beyond the scope of this document, but Scontt Chacon’s Pro git book is an outstanding resource.

Note

  • sudo -Hu root ssh-keygen -t rsa

  • ssh-keygen -t rsa

  • sudo cat /root/.ssh/id_rsa.pub

This will look something like this:

$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/odewahn/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/odewahn/.ssh/id_rsa.
Your public key has been saved in /home/odewahn/.ssh/id_rsa.pub.
The key fingerprint is:
0b:d0:05:60:0a:5a:ed:95:92:07:b1:87:03:e5:2c:75 [email protected]
The key's randomart image is:
+--[ RSA 2048]----+
|. ooB=Eo.        |
|.o B+=+.         |
|. o.B+o          |
|   ..+           |
|      . S        |
|       . .       |
|        .        |
|                 |
|                 |
+-----------------+

$ cat ~/.ssh/id_rsa.pub
ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA6HuZxHII1OFWDY5TIdGlNg0HHfaWwC/ClgHe2WgPezBF3UZPnXnJCUH/ecA3JRnvrcnFlJqKYlNcS/OZz8IguHh3AsNuwbBmDNXS/VB31LcV0gy8TovmEef20n+FO4xF6S4Zsm5Dbz8S/bOtrRxP+X0ujeYr3KOvs7qSq8g4ciVoXf20XJyicnJU2bFJqS5ngVecZd2h1TAvE6SgAEI2+00Bg1r/pbAaV/HNgszlvo++oaiGi88d1kfpdnCmemGYNLccprBgsE9etVYArOI6HiwyswbeRz/b5bgJR1gMwZq8hLMX1IQcMCaFfveG5EL1fYS2nmUl6/GXYTs0dkCeNw== [email protected]

Common use cases when working with git locally

The URI to access the repo on your remote editing environment is very close to the wiki URL, except that you don’t include the "HTTP://". The user name is "git" and the repo name is "git_repo.git." So, if the URL for your editing environment is "http://test.makerpress.com," the URI for your repo will be "[email protected]:git_repo.git". The remainder of this sections describes some of the common use cases for using git locally:

  • If you’re starting push a repo from your local machine to the remote editing environment, do this:

$ cd /the/local/directory
$ git add remote gollum [email protected]
$ git push gollum master

This will push the repo up to your editing environment. This is the way a lot of people start the projects.

  • To clone the repo from the editing environment, you can do this:

$ git clone [email protected]:git_repo.git <local directory name>

This command will pull down the repo into a local folder.

  • Add lots of images or code examples

The "Upload Attachment" feature is nice, but it can be a real drag if you want to add a bunch of images or code examples. Using git locally is one of the best ways to get a bunch of files added quickly. Al you have to do is bring down the repo and put the files into the "attachments" directory. For example:

$ git clone [email protected]:git_repo.git add_images_and_code
$ cd add_images_and_code
$ cd attachments
$ cp /some/image/dir/*.jpg .
$ cp /some/code/dir/*.c .
$ cd ..
$ git add attachments/*.*
$ git commit -a -m"Added a bunch of images and code"
$ git push origin master
$ cd ..
$ rm -rf add_images_and_code

You can not reference all these files in your document, like this:

  image::attachments/new_img.jpg[]
  ...
  include::attachments/new_code.c[]

  • Clean up file names

The native Gollum interface doesn’t allow you to change file names or manipulate the directory structure for your repo. If you want to do this, you can just pull the repo down, make your changes in git, do your commit, and then push some files up. For example:

$ git clone [email protected]:git_repo.git move_files
$ cd move_files
$ git mv crappy_name.asciidoc nice_name.asciidoc
$ git rm unused_file.asciidoc
$ git commit -a -m"Changed some file names"
$ git push origin master
$ cd ..
$ rm -rf move_files

  • Manipulate your repo with scripts

Suppose you want to do something sort of complex, like performing a global search and replace or converting all the URLs in your document into bit.ly links. (Or whatever). To do this, you can simple clone the repo, execute your script (or whatever), commit your changes, and then push the repo back up. For example:

$ git clone [email protected]:git_repo.git manipulate
$ cd manipulate
...
Run script to replace all URLs with equivalent bit.ly links
...
$ git commit -a -m"Changed all links to bit.ly links"
$ git push origin master