DOCUMENTATION

version-control-system

Version control system implemented in python

List of commands

• vcs init

  command format: vcs init <directory path>
  

  This command helps to convert a directory to a repository by creating a vcs subdirectory. vcs subdirectory is named as .vcs and it contains all the commit objects, blobs, tree objects and configuration information. Thus, .vcs directory stores all the changes made in the working tree of the repository. All the commands use the data available in .vcs directory to perform approiate action.

  Directory structure

  root (of directory)
  |
  |_ _ working tree files/sub directories
  |
  |_ _ .vcs (vcs directory)
       |
       |_ _ config (file which stores configuration info which is used by vcs program)
       |
       |_ _ HEAD (file which stores the location of the object storing the latest commit)
       |
       |_ _ objects (directory --> holds all the objects which are serialized and stored in memory)
       |
       |_ _ branches (directory)
       |
       |_ _ refs (directory)
       |     |
       |     |_ _ tags (directory)
       |     |
       |     |_ _ heads (directory)
       |
       |_ _ description (file which stores the description of the repository)

  

  

• vcs hash-object

  command format: vcs hash-object [-w] [-t TYPE] FILE
  

  This command reads a file and computes the hash of the content of the file. if -w flag is provided, then the file is content of the file is converted to a vcs object which is then serialized and then compressed and then stored in the .vcs/objects directory.

  Types of objects:

  • Blob: These objects are the common type of objects and contents of file in working directory and some other files are stored in such objects.
  • commit: These objects store the commit information.
  • tree: These objects store the tree information.
  • tag: These objects store the tag data.

  Every object which is serialized and stored as the file in the directory .vcs/object follows a generic format. The format is:

  <header> + <whitespace> + <object size> + <null separator (0x00)> + <byte string of the object>
  

  The content of the file is in byte string format.

  

• vcs cat-file

  command format: vcs cat-file TYPE OBJECT
  

  This command reads a file storing the serialized object and then deserializes it into a python object of class TYPE. This command does the opposite of what command hash-object does. While deserializing, this command checks if object size matches the size mentioned in file, thus, data malformation is detected.

  

• vcs log

  command format: vcs log [-d] <commit hash>
  

  This command displays the commit history in a repository starting from the commit whose hash value is passed as the argument. At this point, commit information is not displayed but further commit information can be displayed by passing the commit hash to the vcs cat-file function. If [commit hash] is empty, then the commit log is shown from HEAD commit (latest commit).
  The optional flag [ -d ] when mentioned leads to commit log being printed in a graphviz format.

  • commit log in graphviz format

  command: vcs log -d <commit hash> >> log.dot  
  command: dot -O -Tpdf log.dot
  

  Note: Install Graphviz as dependency

  

• vcs ls-tree

  command format: vcs ls-tree [tree object hash]
  

  This command pretty prints the tree object provided as argument. The hash value of the tree object is passed as the argument. The hash value of tree object can be obtained from a commit object. By pretty printing a commit object using vcs cat-file command, hash value of a tree object can be obtained.

  

• vcs commit

  command format: vcs commit [-a] [commit message]
  

  This command basically creates a snapshot of the current directory and stores it in the .vcs directory and returns a commit hashvalue (commit id), which is the id of the snapshot. Each snapshot stores the state of the directory at the point of time when commit command is executed. The latest commit is also referred to as HEAD commit. HEAD: Latest commit (last commit of a repository). It is essential to provide a commit message while executing a commit command. Without a commit message, a commit command will not execute. A commit message should be meaningful, which explains what are the changes that are being made in the repository since last commit.
  If no changes has been made since last commit in the current repository, no commit will be done. In such case, following message will be displayed:

  Nothing to commit. No change in worktree since last commit [HEAD commit hash]
  

  The [-a] flag is a optional flag which when provided indicates that the user is only author of the commit and not the commiter of the commit. In this case, the author only creates the commit while some other person who is the commiter, reviews and adds the commit to the commit chain.

  NOTE

  Make sure to set the user name and email-id using the [vcs set command] before using the vcs commit  
  command for the first time. User name and email-id is included in the commit object to identify the  
  author of the commit.
  

  

• vcs set

  command format: vcs set [--name] [--email]
  

  This command basically sets the user name and email-id of a person. This information is included in the commit as the commit author contact information or committer contact information. This is important so that in future, other people using the repository can identify which person made certain changes to the repository. This helps to establish a decentralized elementary blame system for the changes made in the repository, which is used by many people. To set or update the username, pass the name flag succeded with the username and to set or update the email-id, pass the email flag succeded with the email-id.

• vcs checkout

    command format: vcs checkout [commit] [path]
  

  This command stores the previous state of the current repository which is marked by a commit previously made, in a empty directory pointed by the [path] argument. Thus, this command helps the user to rollback to a previous version of the current repository. The path should point to a empty directory and the commit passed as argument should be valid. Both the arguments commit and path are required. One can checkout to the latest commit by passing HEAD as the value of the commit argument instead of the commit hash value.

  If path doesn't exist, then the path will be created or if the directory doesn't exist, then a empty directory of the same name will be created where the rollback version of the repository will be initalized.