RoboCup Docs GIT HOWTO

From GT RoboJackets

Jump to: navigation, search

We store our documents, like TDP drafts on the Git repository used by software and electrical currently. Git can be accessed from Linux systems using command line tools, or through Windows with a GUI as well. For a more detailed usage guide for accessing git, see the Software GIT HOWTO.

Note: for Ubuntu users, install packages by searching for them through either Synaptic or Ubuntu Software Center.

Contents

Instructions

Getting repository access

Before using Git, you will need to have an ssh account on our server to get access. Contact the robojackets network manager to create an account. You should have sufficient information from the checkout command to be able to use either the command line version of git on linux, or set up a Windows git client. Be sure to note your RJ account name and password, as you will use it in the following instructions. It is in no way connected to any other GT credentials.

Installing Software: Git

To access and make changes to the documentation, you will need to use a Git client. Git is a version control system, similar to CVS, SVN or Bazaar, and there are lots of instructions around the internet for using it.

For Ubuntu:

  • Install the git and gitk packages to get the command line version of the software and a useful GUI
  • You can run git from the command line, or use the gitk interface

For Windows:

  • Download and install TortoiseGit, which will integrate Git functionality into Windows Explorer. You may need to download additional things from the TortoiseGit website, such as msysgit, so follow their instructions for setup.

Installing Software: Lyx

To get a crossplatform, easy-to-use editor for writing Latex, we use Lyx, which provides a very usable frontend. Be sure the version number is 2.0 or greater (latest is 2.0.2), rather than the older 1.6.X versions, as the older version aren't compatible with newer files. Note that you will also need to install a Latex implementation when you install Lyx as well.

For Ubuntu:

  • Install the package lyx to get the latest version of Lyx. This will get all of the dependencies.
  • You may also need to install additional latex packages (TODO: determine necessary set for this)

For Windows:

  • Download and install from here you'll want the bundled one so you don't have to download more things during installation.

Checking Out RC Docs

To actually check out a local copy of RC docs, you can use the following command in a command line: 

git clone ssh://[username]@robojackets.org/git/robocup/docs docs

where [username] is your Robojackets username on the server. When you perform the checkout, you will be asked for your RJ password.

In Windows, after installing ToroiseGit, you can check out a project by right-clicking in a folder and selecting checkout from the TortoiseGit options that appear in the menu.

Basics of Git

The instructions on the Software GIT HOWTO page go into more detail on how to use git. In general, the command git status is your friend and will tell you what to do.

Basic workflow

  • Check out a copy of the docs repository (described above) - you will now have a copy of everything on your system
  • Change stuff (editting documents, adding files, etc) - use Lyx and other tools for this
  • Commit your local changes: do this to have git save a snapshot of the current state of your files.
    • Use the command git commit -a to commit all modified files to your local repository.
    • If you add new files, use git add first.
    • To see what has changed, use git status, and follow its instructions for adding unversioned files and updating modified ones.
  • Now that you've recorded you changes, use git pull to get any new changes from the server that went up since you last updated
  • If there are no conflicts, use git push to move your committed changes back to the repository for others to access.

Conventions

Git and file management

  • Do not commit temporary files to the repository, as these will conflict with others as the paper is edited.
  • Always add a commit log for when you commit changes so it is possible to tell what has changed.
  • Commit updates frequently, in small chunks, rather than doing a large amount of work many places and checking it all in at once. This will help prevent conflicts.

Writing

  • Don't use passive voice to try to sound smart, just say "we" or "our".
  • This is a proposal for what we will have done by competition, so much of the document will either be written in the past tense (when describing results from last year) or future tense (anything we plan to have done later)
  • Bullet points are your friend: anytime you have lists, consider bullets.
Retrieved from "http://wiki.robojackets.org/w/RoboCup_Docs_GIT_HOWTO"
Personal tools