Difference between revisions of "Git"

From SleuthKitWiki
Jump to: navigation, search
Line 1: Line 1:
 
This page outlines how to use git to get the Sleuth Kit source code.  It assumes basic familiarity with git, but maybe not all of the nuances of working with git submodules.  
 
This page outlines how to use git to get the Sleuth Kit source code.  It assumes basic familiarity with git, but maybe not all of the nuances of working with git submodules.  
  
 
+
==Getting a Read Only Copy of Sleuth Kit Core==
=Getting a Read Only Copy of Sleuth Kit Core=
+
 
If you only want to get a copy of the core TSK (i.e. not the [[framework]]) and do not intend to make updates, then clone the main repository:
 
If you only want to get a copy of the core TSK (i.e. not the [[framework]]) and do not intend to make updates, then clone the main repository:
  
Line 11: Line 10:
 
This will download the basics of the framework, but not the modules.   
 
This will download the basics of the framework, but not the modules.   
  
=Getting a Read/Write Copy of Sleuth Kit Core=
+
==Getting a Read/Write Copy of Sleuth Kit Core==
If you want to modify the code and submit changes, then fork the github repository into your own github account.  Make changes there and submit a pull request.
+
If you want to modify the code and submit changes, then [http://help.github.com/fork-a-repo/ fork] the github repository into your own github account.  Commit and push changes into your repository and then submit a pull request using the web app (for example). We'll review them and merge them in.
 +
 
  
 +
==Sleuth Kit Framework==
 +
=== Submodule Basics ===
 +
If you want to fully build TSK and the framework, then you'll need to also pull in the submodules.  The C++ modules that run inside of the framework are in separate repositories.  This allows each to  have its own version, tags, etc.
  
=Sleuth Kit Framework=
+
The framework code uses git [http://git-scm.com/book/en/Git-Tools-Submodules submodules] to bring those modules into the framework.  For example, the module that opens ZIP files is named c_ZIPExtractionModuleIt has its own [http://github.com/sleuthkit/c_ZIPExtractionModule repository]. The sleuthkit git repository includes the ZIP extraction module using git submodules into the 'framework/TskModules/c_ZIPExtractionModule' folderThere are several submodules in that folder.
== Submodules ==
+
If you want to fully build TSK and the framework, then you'll need to also pull in the submodulesThe C++ modules that run inside of the framework are in separate repositories.  The framework code uses git submodules to bring those modules into the framework.   
+
  
For example, the module that opens ZIP files is named c_ZIPExtractionModule.  It has its own [ https://github.com/sleuthkit/c_ZIPExtractionModule | repository]. The sleuthkit git repository includes the ZIP extraction module using git submodules into the 'framework/TskModules/c_ZIPExtractionModule' folder.  There are several submodules in that folder.  
+
The sleuthkit repository knows where to find the repositories that are included as submodules and it knows about a specific commit version that it wants from that repository.  
  
== Cloning ==
+
=== Cloning ===
 
To get all of the submodules from the clone, you should use --recursive.  For example, to clone the official repo you would use:
 
To get all of the submodules from the clone, you should use --recursive.  For example, to clone the official repo you would use:
  
Line 28: Line 29:
 
</pre>
 
</pre>
  
Otherwise, you will need to use:
+
If you don't use --recursive, then you'll also need to run the following to populate the submodule folders (they will be empty by default)
 
<pre>
 
<pre>
 
git submodule init
 
git submodule init
Line 34: Line 35:
 
</pre>
 
</pre>
  
You will also need to use '--recursive' if you forked the main repository and are working from that.
+
You will need to use one of these approaches regardless of whether you are forking the main repository or a copy of it that is in your github account.  
  
== Updating Code ==
+
=== Updating Code ===
 
Submodules are not updated automatically when you do a 'git pull' in the sleuthkit repository.  To update all of the modules, you will need to do:
 
Submodules are not updated automatically when you do a 'git pull' in the sleuthkit repository.  To update all of the modules, you will need to do:
- X   
+
- X (I think it's just submodule update -- need to test if pull does it too)    
  
== Committing Changes to Modules ==
+
=== Committing Changes to Modules ===
 
If you want to develop on an official module (c_FooModule for this example) and be able to submit the changes, then follow these steps:
 
If you want to develop on an official module (c_FooModule for this example) and be able to submit the changes, then follow these steps:
 
# Fork the main sleuthkit repository into your github account and clone it into a local repository / directory (remember to use --recursive on the clone).
 
# Fork the main sleuthkit repository into your github account and clone it into a local repository / directory (remember to use --recursive on the clone).
# Fork the c_FooModule repository into your github account.  You don't need to clone this.
+
# Fork the c_FooModule repository into your github account.  You don't need to clone this, but you will need to use the URL later when we do a push.  
 
# Make the changes to the module in its 'framework/TskModules/c_FooModule' location. Before you make changes, ensure that you are on the master branch using 'git checkout master'.  By default, you are not on master with submodules.  
 
# Make the changes to the module in its 'framework/TskModules/c_FooModule' location. Before you make changes, ensure that you are on the master branch using 'git checkout master'.  By default, you are not on master with submodules.  
# Commit the module changes by doing a 'git commit' from inside of the c_FooModule directory.  
+
# Commit the module changes by doing a 'git commit' from inside of the c_FooModule directory.  You can't commit them from the main sleuthkit repo.  
# Push them to the fork in your account by using your fork of c_FooModule as a remote host.  
+
# Push the changes to the fork in your account by using your account as a remote host.  
 
<pre>
 
<pre>
 
git remote add myfork git@github.com:user_name/c_FooModule.git
 
git remote add myfork git@github.com:user_name/c_FooModule.git
Line 63: Line 64:
 
If you do this, then you can simply do a 'git push' from inside the module and it will send the changes to your github repository instead of the sleuthkit repository.  You can then do a pull request to get it moved over.  
 
If you do this, then you can simply do a 'git push' from inside the module and it will send the changes to your github repository instead of the sleuthkit repository.  You can then do a pull request to get it moved over.  
  
== Updating Modules ==
+
=== Updating Modules ===
 
If you find that the sleuthkit repository is not pulling down the latest and greatest version of the modules, then either we don't feel that they are ready for prime time or we messed up and forgot to update the sleuthkit repository.  To get the latest and greatest, the following all are equivalent:
 
If you find that the sleuthkit repository is not pulling down the latest and greatest version of the modules, then either we don't feel that they are ready for prime time or we messed up and forgot to update the sleuthkit repository.  To get the latest and greatest, the following all are equivalent:
- git pull  (from inside of the submodule -- this needs to be repeated for each submodule)
+
* <tt>git pull</tt> (from inside of the submodule -- this needs to be repeated for each submodule)
- git pull --recursive-submodules=true  (from inside of the sleuthkit repository -- gets all modules)
+
* <tt>git pull --recursive-submodules=true</tt> (from inside of the sleuthkit repository -- gets all modules)
- git submodule foreach git pull  (from inside of the sleuthkit repository -- gets all modules)
+
* <tt>git submodule foreach git pull</tt> (from inside of the sleuthkit repository -- gets all modules)
  
 
Note that all of these will update the sleuthkit repository to use the version of the modules that were pulled down.  So, you will see that a git status shows that your repository has changed.
 
Note that all of these will update the sleuthkit repository to use the version of the modules that were pulled down.  So, you will see that a git status shows that your repository has changed.

Revision as of 14:21, 15 May 2012

This page outlines how to use git to get the Sleuth Kit source code. It assumes basic familiarity with git, but maybe not all of the nuances of working with git submodules.

Getting a Read Only Copy of Sleuth Kit Core

If you only want to get a copy of the core TSK (i.e. not the framework) and do not intend to make updates, then clone the main repository:

git clone git://github.com/sleuthkit/sleuthkit.git

This will download the basics of the framework, but not the modules.

Getting a Read/Write Copy of Sleuth Kit Core

If you want to modify the code and submit changes, then fork the github repository into your own github account. Commit and push changes into your repository and then submit a pull request using the web app (for example). We'll review them and merge them in.


Sleuth Kit Framework

Submodule Basics

If you want to fully build TSK and the framework, then you'll need to also pull in the submodules. The C++ modules that run inside of the framework are in separate repositories. This allows each to have its own version, tags, etc.

The framework code uses git submodules to bring those modules into the framework. For example, the module that opens ZIP files is named c_ZIPExtractionModule. It has its own repository. The sleuthkit git repository includes the ZIP extraction module using git submodules into the 'framework/TskModules/c_ZIPExtractionModule' folder. There are several submodules in that folder.

The sleuthkit repository knows where to find the repositories that are included as submodules and it knows about a specific commit version that it wants from that repository.

Cloning

To get all of the submodules from the clone, you should use --recursive. For example, to clone the official repo you would use:

git clone --recursive git://github.com/sleuthkit/sleuthkit.git

If you don't use --recursive, then you'll also need to run the following to populate the submodule folders (they will be empty by default)

git submodule init
git submodule update

You will need to use one of these approaches regardless of whether you are forking the main repository or a copy of it that is in your github account.

Updating Code

Submodules are not updated automatically when you do a 'git pull' in the sleuthkit repository. To update all of the modules, you will need to do: - X (I think it's just submodule update -- need to test if pull does it too)

Committing Changes to Modules

If you want to develop on an official module (c_FooModule for this example) and be able to submit the changes, then follow these steps:

  1. Fork the main sleuthkit repository into your github account and clone it into a local repository / directory (remember to use --recursive on the clone).
  2. Fork the c_FooModule repository into your github account. You don't need to clone this, but you will need to use the URL later when we do a push.
  3. Make the changes to the module in its 'framework/TskModules/c_FooModule' location. Before you make changes, ensure that you are on the master branch using 'git checkout master'. By default, you are not on master with submodules.
  4. Commit the module changes by doing a 'git commit' from inside of the c_FooModule directory. You can't commit them from the main sleuthkit repo.
  5. Push the changes to the fork in your account by using your account as a remote host.
git remote add myfork git@github.com:user_name/c_FooModule.git
git push myfork

You need to add the remote host only once.

  1. The previous commit will have updated your sleuthkit repository to reflect the new commit version. So, you'll need to also do a commit and push to your fork of the sleuthkit repository to your github account.
  2. Issue pull requests for both the module and sleuthkit repositories.

An alternative method of pushing the changes to your repository instead of the 'remote add' step is to update the 'pushurl' for the default 'origin' repository to point to your copy. Something like this from inside the module:

git config --add remote.origin.pushurl git@github.com:user_name/c_FooModule.git

If you do this, then you can simply do a 'git push' from inside the module and it will send the changes to your github repository instead of the sleuthkit repository. You can then do a pull request to get it moved over.

Updating Modules

If you find that the sleuthkit repository is not pulling down the latest and greatest version of the modules, then either we don't feel that they are ready for prime time or we messed up and forgot to update the sleuthkit repository. To get the latest and greatest, the following all are equivalent:

  • git pull (from inside of the submodule -- this needs to be repeated for each submodule)
  • git pull --recursive-submodules=true (from inside of the sleuthkit repository -- gets all modules)
  • git submodule foreach git pull (from inside of the sleuthkit repository -- gets all modules)

Note that all of these will update the sleuthkit repository to use the version of the modules that were pulled down. So, you will see that a git status shows that your repository has changed.