====== Working with the Tape Archive Utility (TAR) ======

To make a tar file from the directory homework1

<code>
$ tar czf homework1.tgz homework1
</code>
To check the contents of a tar file called homework1.tgz

<code>
$ tar tzf homework.tgz
</code>
To extract the contents of a tar file called homework1.tgz

<code>
$ tar xzf homework1.tgz
</code>
     

===== Overview =====
tar or the Tape ARchive utility is a program that is used for combining multiple files into a single file.  This is the format that is used to transfer multiple files in the majority of open source project.

Tar files are frequently used to transfer the contents of a directory.  The examples on this page assume that you want to transfer all of the files in a directory called ** homework1 **.  Further assume the contents of this directory are two files, ** hello.cpp** and ** Makefile **.

<code>
$ ls
Makefile  hello.cpp
</code>

Files created with tar frequently have the extension .tar.  The file // homework1.tar // is the conventional name used for a tar file containing the directory homework1.

Tar is frequently used in conjunction with compression utilities.  GNU zip (gzip) is a common choice for this.   A tar file which has been compressed with gzip will frequently have the extension .tgz or even .tar.gz.  In this case // homework1.tgz // or //homework1.tar.gz // are the conventional  names for a tar file containing the directory homework1 which has been compressed with gzip.

This page is a summary, there are other ways that tar can be employed.

===== Creating a TAR File =====

The best practice is to work on each project in a folder or directory.  For this example the code for a project is located in the directory homework1.  

  - Move one directory above the homework1 directory
    - If you can see the directory you wish to create a tar archive of when you type ls  you are in the correct directory.
<code>
$ ls 
homework1
</code>
  -  type the command ** tar cvzf homework1.tgz homework1 **
    - ** c ** tells tar to create a tar archive.
    - ** v ** tells tar to show you what it is adding to the archive
    - ** z ** tells tar to use gnuzip to compress the resulting file
    - ** f ** tells tar to write the output to a file, not to the tape devuce
    - ** homework1.tgz ** is the name of the output file.
    - ** homework1 ** is the name of the directory you wish to place in the tar file
<code>
$ tar cvzf homework1.tgz homework1
</code>

In the following example the user types ** ls ** to show that the directory homework1 exists.  After that, the tar command to create a tar file is issued.  This command is run in verbose mode so each file or directory is listed as it is added to the tar file.  The example concludes with a listing of the directory showing that the tar file ** homework1.tgz ** has been created.

<code>
$ ls
homework1

$ tar cvzf homework1.tgz homework1
homework1/
homework1/Makefile
homework1/hello.cpp

$ ls
homework1  homework1.tgz
</code>

===== Checking the Contents of a TAR File =====

To check the contents of a tar file use the following command in the directory containing the tar file.
<code>
$ tar tzf homework1.tgz
</code>

Note that in this command ** c ** has been replaced with ** t ** which means table of contents.

<code>
$ ls
homework1  homework1.tgz

$ tar tzf homework1.tgz 
homework1/
homework1/Makefile
homework1/hello.cpp
</code>


===== Extracting files from a TAR File =====

To extract the contents of a tar file
  * The tar file should be located in the current working directory.
  * Any files matching those in the tar file will be replaced.

In the tar command, ** c ** should be replaced with ** x **, which tells tar to extract the contents of the file.

<code>
$ tar xzf homework1.tgz
</code>

In the following example
  * The user types ** ls ** to show the contents of the current directory.
  * The user issues the tar command to extract the contents of a file.
    * The addition of the ** v ** flag tells tar to be verbose, ie show the files as they are extracted.
  * The user types ** ls ** again to show that the directory homework1 has been created.
  * The user types ** ls -r homework1 ** to show the files have been extracted in the homework1 directory
<code>

$ ls
homework1.tgz

$ tar xvzf homework1.tgz 
homework1/
homework1/Makefile
homework1/hello.cpp

$ ls
homework1  homework1.tgz

$ ls -r homework1
hello.cpp  Makefile

</code>

===== Tar Files and WinSCP =====

WinSCP has the ability to deal with tar files.

To create a tar file of a directory
  * Select the directory
  * Right click and select ** File Custom Commands **
  * Select ** Tar/GZip **
  * {{:guides:tar1.png?nolink|}}
  * You may have to allow a new ssh session
  * Provide the name for the tar file.
  * {{:guides:tar3.png?nolink|}}
  * Notice the new tar file is located in the current directory.
  * {{:guides:tar4.png?nolink|}}