|
|
| (17 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| __TOC__
| | The instructions previously available on this page have been superseded. See [https://gitlab.kitware.com/paraview/paraview/blob/master/Documentation/dev/git/README.md here]. |
| | |
| ParaView version tracking and development is hosted by [http://git-scm.com Git].
| |
| | |
| =Official Repository=
| |
| | |
| One may browse the repository online using the [http://git.wiki.kernel.org/index.php/Gitweb Gitweb] interface at http://paraview.org/gitweb.
| |
| | |
| ==Cloning==
| |
| | |
| Clone ParaView using the command
| |
| | |
| $ git clone --recursive git://paraview.org/ParaView.git
| |
| | |
| This requires Git 1.6.5 or higher. If you do not have it, see [[#Git Below 1.6.5|below]].
| |
| If your institution's firewall blocks the Git port for outgoing connections, see [[#Firewall_Blocks_Port_9418|below]].
| |
| | |
| The clone URLs for the repository are | |
| | |
| git://paraview.org/ParaView.git
| |
| http://paraview.org/ParaView.git
| |
| | |
| The push URL for the repository is
| |
| | |
| git@paraview.org:ParaView.git
| |
| | |
| For ParaViewData the URLs are
| |
| | |
| git://paraview.org/ParaViewData.git
| |
| http://paraview.org/ParaViewData.git
| |
| git@paraview.org:ParaViewData.git
| |
| | |
| All further commands work inside the local copy of the repository created by the clone. See the [[VTK/Git | VTK]] Git documentation for further details.
| |
| | |
| ==Branches==
| |
| | |
| At the time of this writing the repository has the following branches:
| |
| | |
| * '''master''': Development (default)
| |
| * '''release''': Release preparation branch (prior to switching to a brancy workflow; may go away later)
| |
| * '''hooks''': Local commit hooks ([[VTK/Git#Hooks|place]] in .git/hooks)
| |
| | |
| Release branches converted from CVS have been artificially merged into master. Actual releases have tags named by the release version number.
| |
| | |
| ==Initializing the Submodules==
| |
| | |
| ParaView references a few other projects as ''submodules''. They can be obtained using the [http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html git submodule] command.
| |
| First use the 'init' subcommand to register the submodules:
| |
| | |
| $ git submodule init
| |
| | |
| This configures the submodules to fetch from their default URLs, such as <code>git://vtk.org/VTK.git</code> for VTK.
| |
| Next one may optionally configure a different URL, perhaps to use the http protocol:
| |
| | |
| <pre>$ git config submodule.VTK.url http://vtk.org/VTK.git</pre>
| |
| | |
| (and similarly for other submodules if necessary).
| |
| Finally, use the 'update' subcommand to get the submodules:
| |
| | |
| $ git submodule update
| |
| | |
| Whenever you update your work tree to some revision of ParaView then 'git status' may report that the submodule directories are modified. This is because commands like 'git checkout' do not automatically update submodules. Use 'git submodule update' at any time to ensure that the submodule directories are updated to the versions referenced by the parent project.
| |
| | |
| ===VTK===
| |
| | |
| ParaView references VTK as a ''submodule'' called '<code>VTK</code>'.
| |
| Repository URLs:
| |
| | |
| git://vtk.org/VTK.git
| |
| http://vtk.org/VTK.git
| |
| git@vtk.org:VTK.git
| |
| | |
| ===IceT===
| |
| | |
| ParaView references IceT as a ''submodule'' called '<code>IceT</code>' at path '<code>Utilities/IceT</code>'.
| |
| Repository URLs:
| |
| | |
| git://paraview.org/IceT.git
| |
| http://paraview.org/IceT.git
| |
| git@paraview:IceT.git
| |
|
| |
| git://public.kitware.com/IceT.git
| |
| http://public.kitware.com/IceT.git
| |
| git@public.kitware.com:IceT.git
| |
| | |
| ===Xdmf===
| |
| | |
| ParaView references Xdmf as a ''submodule'' called '<code>Xdmf</code>' at path '<code>Utilities/Xdmf2</code>'.
| |
| Repository URLs:
| |
| | |
| git://paraview.org/Xdmf.git
| |
| http://paraview.org/Xdmf.git
| |
| git@paraview:Xdmf.git
| |
|
| |
| git://public.kitware.com/Xdmf.git
| |
| http://public.kitware.com/Xdmf.git
| |
| git@public.kitware.com:Xdmf.git
| |
| | |
| =Submodules=
| |
| | |
| ParaView references the VTK repository as a ''submodule'' (and a few other projects too).
| |
| See the [http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html git submodule] command documentation.
| |
| | |
| ==Introduction==
| |
| | |
| After the initial clone, Git does not tell you anything special about submodules by default:
| |
| | |
| $ git status
| |
| # On branch master
| |
| nothing to commit (working directory clean)
| |
| | |
| However, the Git submodule porcelain does:
| |
| | |
| $ git submodule status
| |
| -432f38d95bfa3c68d1345917680f4d2b4d1267c4 Utilities/IceT
| |
| -17f7aadc96a0a72c0f8f6e21cd37900db73b1b1f Utilities/Xdmf2
| |
| -3bc24abbd97b3d63574e1bafb91948a61033af34 VTK
| |
| | |
| This says that the currently checked out version of ParaView points to commit <code>3bc24abb</code> from VTK.
| |
| The "-" prefix means that the VTK submodule is ''not checked out'' in the current work tree.
| |
| We can confirm this by looking at the VTK directory:
| |
| | |
| $ ls -a VTK/
| |
| ./ ../
| |
| | |
| Even though VTK is not there, the current version of ParaView knows what version of VTK it wants.
| |
| We can see this by using Git plumbing commands to list the content of the top-level tree:
| |
| | |
| $ git ls-tree HEAD | tail -3
| |
| 040000 tree d46aa321e9971c38f484350a2d0495183a0cc517 Utilities
| |
| 160000 commit 3bc24abbd97b3d63574e1bafb91948a61033af34 VTK
| |
| 100644 blob 1cdb942f9a8c9e13a1e3da52b6fdbe522626981a vtkPVConfig.h.in
| |
| | |
| Note that the entry for "VTK" is not a blob or a tree...it's a commit!
| |
| The commit is not necessarily known to the ParaView/.git repository because it comes from VTK.
| |
| We can see the commit here: [http://vtk.org/gitweb?p=VTK.git;a=commitdiff;h=3bc24abb 3bc24abb]
| |
| | |
| In order to get VTK we need to ask Git to checkout the submodules:
| |
| | |
| $ git submodule init
| |
| Submodule 'IceT' (git://paraview.org/IceT.git) registered for path 'Utilities/IceT'
| |
| Submodule 'Xdmf' (git://paraview.org/Xdmf.git) registered for path 'Utilities/Xdmf2'
| |
| Submodule 'VTK' (git://vtk.org/VTK.git) registered for path 'VTK'
| |
| $ git submodule update
| |
| Initialized empty Git repository in /path/to/ParaView/Utilities/IceT/.git/
| |
| ...
| |
| Submodule path 'Utilities/IceT': checked out '432f38d95bfa3c68d1345917680f4d2b4d1267c4'
| |
| Initialized empty Git repository in /path/to/ParaView/Utilities/Xdmf2/.git/
| |
| ...
| |
| Submodule path 'Utilities/Xdmf2': checked out '17f7aadc96a0a72c0f8f6e21cd37900db73b1b1f'
| |
| Initialized empty Git repository in /path/to/ParaView/VTK/.git/
| |
| ...
| |
| Submodule path 'VTK': checked out '3bc24abbd97b3d63574e1bafb91948a61033af34'
| |
| | |
| Now Git's submodule porcelain reports
| |
| | |
| $ git submodule status
| |
| 432f38d95bfa3c68d1345917680f4d2b4d1267c4 Utilities/IceT (432f38d)
| |
| 17f7aadc96a0a72c0f8f6e21cd37900db73b1b1f Utilities/Xdmf2 (17f7aad)
| |
| 3bc24abbd97b3d63574e1bafb91948a61033af34 VTK (v5.4.2-4340-g3bc24ab)
| |
| | |
| Note the leading space on each line.
| |
| This means that the submodule is checked out to the version that our current ParaView version references.
| |
| We can confirm this by looking in VTK:
| |
| | |
| $ cd VTK
| |
| VTK$ git rev-parse HEAD
| |
| 3bc24abbd97b3d63574e1bafb91948a61033af34
| |
| | |
| Note that the VTK work tree is on a ''detached head'', meaning that its <code>HEAD</code> does not point at a branch but instead directly at a commit:
| |
| | |
| VTK$ cat .git/HEAD
| |
| 3bc24abbd97b3d63574e1bafb91948a61033af34
| |
| VTK$ git status
| |
| # Not currently on any branch.
| |
| nothing to commit (working directory clean)
| |
| VTK$ git branch
| |
| * (no branch)
| |
| master
| |
| VTK$ cd ..
| |
| | |
| This is because the submodule reference stored in ParaView (3bc24abb) does not refer to a branch of VTK, but the specific commit.
| |
| | |
| Look at the log of the VTK submodule in ParaView:
| |
| | |
| $ git log -p -- VTK
| |
| commit 71e7789b18f8006010d6989baa6ced79dc2e3f96
| |
| ...
| |
| diff --git a/VTK b/VTK
| |
| index 46a8f04..3bc24ab 160000
| |
| --- a/VTK
| |
| +++ b/VTK
| |
| @@ -1 +1 @@
| |
| -Subproject commit 46a8f04a3d6084d18136ac6e51c3eb2685907497
| |
| +Subproject commit 3bc24abbd97b3d63574e1bafb91948a61033af34
| |
|
| |
| commit 9f88e601468ecda4c3f52dd07c36b7c275646855
| |
| ...
| |
| diff --git a/VTK b/VTK
| |
| index 8920140..46a8f04 160000
| |
| --- a/VTK
| |
| +++ b/VTK
| |
| @@ -1 +1 @@
| |
| -Subproject commit 892014037f07ac668979c85b85112fc850515b94
| |
| +Subproject commit 46a8f04a3d6084d18136ac6e51c3eb2685907497
| |
| ...
| |
| | |
| Note that this does not show the changes in VTK, but rather the changes to the version of VTK that ParaView ''references''.
| |
| | |
| '''Think of VTK as a ''file'' in ParaView that specifies the version of VTK to use.'''
| |
| The content of this "file" is the version of VTK that is checked out in the VTK subdirectory.
| |
| We can see this by changing the version of VTK in our work tree:
| |
| | |
| $ cd VTK
| |
| VTK$ git checkout 'HEAD^'
| |
| VTK$ cd ..
| |
| | |
| Now our ParaView repository sees that we've modified "VTK":
| |
| | |
| $ git status
| |
| # On branch master
| |
| # Changed but not updated:
| |
| # (use "git add <file>..." to update what will be committed)
| |
| # (use "git checkout -- <file>..." to discard changes in working directory)
| |
| #
| |
| # modified: VTK
| |
| #
| |
| no changes added to commit (use "git add" and/or "git commit -a")
| |
| $ git submodule status
| |
| 432f38d95bfa3c68d1345917680f4d2b4d1267c4 Utilities/IceT (432f38d)
| |
| 17f7aadc96a0a72c0f8f6e21cd37900db73b1b1f Utilities/Xdmf2 (17f7aad)
| |
| +81de700ff1bb6752b4f9710c49ca7454ee2889ae VTK (v5.4.2-4339-g81de700)
| |
| | |
| The leading "+" means that the submodule is checked out to a different version than that referenced.
| |
| We can see the modification just like any other file:
| |
| | |
| $ git diff
| |
| diff --git a/VTK b/VTK
| |
| index 3bc24ab..81de700 160000
| |
| --- a/VTK
| |
| +++ b/VTK
| |
| @@ -1 +1 @@
| |
| -Subproject commit 3bc24abbd97b3d63574e1bafb91948a61033af34
| |
| +Subproject commit 81de700ff1bb6752b4f9710c49ca7454ee2889ae
| |
| | |
| At any time we can ask Git to checkout the version that ParaView wants:
| |
| | |
| $ git submodule update
| |
| Submodule path 'VTK': checked out '3bc24abbd97b3d63574e1bafb91948a61033af34'
| |
| $ git status
| |
| # On branch master
| |
| nothing to commit (working directory clean)
| |
| $ cd VTK
| |
| VTK$ git rev-parse HEAD
| |
| 3bc24abbd97b3d63574e1bafb91948a61033af34
| |
| VTK$ cd ..
| |
| | |
| ==Commits outside VTK==
| |
| | |
| In order to commit a change to ParaView that does not involve VTK, avoid staging VTK before commit.
| |
| For example, let's edit CTestConfig.cmake and stage it:
| |
| | |
| $ vi CTestConfig.cmake
| |
| $ git add CTestConfig.cmake
| |
| | |
| Now check the status:
| |
| | |
| $ git status
| |
| # On branch master
| |
| # Changes to be committed:
| |
| # (use "git reset HEAD <file>..." to unstage)
| |
| #
| |
| # modified: CTestConfig.cmake
| |
| #
| |
| | |
| In practice we might see VTK as modified:
| |
| | |
| $ git status
| |
| # On branch master
| |
| # Changes to be committed:
| |
| # (use "git reset HEAD <file>..." to unstage)
| |
| #
| |
| # modified: CTestConfig.cmake
| |
| #
| |
| # Changed but not updated:
| |
| # (use "git add <file>..." to update what will be committed)
| |
| # (use "git checkout -- <file>..." to discard changes in working directory)
| |
| #
| |
| # modified: VTK
| |
| #
| |
| | |
| This is okay, just don't use "git commit -a".
| |
| Now we can commit:
| |
| | |
| $ git commit
| |
| Removed unnecessary comment in CTest configuration
| |
| | |
| The comment was generated by CDash. Since we've already followed its
| |
| instructions we do not need it anymore.
| |
| | |
| Before publishing, make sure that the VTK "file" was not changed:
| |
| | |
| $ git show --stat
| |
| commit bd7970c0818007531298cb3cfb32cb6c79c1a4ad
| |
| Author: Brad King <brad.king@kitware.com>
| |
| Date: Thu Apr 22 14:42:34 2010 -0400
| |
|
| |
| Removed unnecessary comment in CTest configuration
| |
|
| |
| The comment was generated by CDash. Since we've already followed its
| |
| instructions we do not need it anymore.
| |
|
| |
| CTestConfig.cmake | 6 ------
| |
| 1 files changed, 0 insertions(+), 6 deletions(-)
| |
| | |
| If we had accidentally included VTK in the commit, we might have seen this in the output:
| |
| | |
| CTestConfig.cmake | 6 ------
| |
| VTK | 2 +-
| |
| 2 files changed, 1 insertions(+), 7 deletions(-)
| |
| | |
| Do not publish this commit. Amend it to create a commit that does not update VTK.
| |
| First, reset the index to point at the VTK referenced by the commit's parent:
| |
| | |
| $ git reset 'HEAD^' -- VTK
| |
| $ git status
| |
| # On branch master
| |
| # Your branch is ahead of 'origin/master' by 1 commit.
| |
| #
| |
| # Changes to be committed:
| |
| # (use "git reset HEAD <file>..." to unstage)
| |
| #
| |
| # modified: VTK
| |
| #
| |
| # Changed but not updated:
| |
| # (use "git add <file>..." to update what will be committed)
| |
| # (use "git checkout -- <file>..." to discard changes in working directory)
| |
| #
| |
| # modified: VTK
| |
| #
| |
| | |
| Since the command just reset the index and we never ran 'git submodule update', the work tree appears modified ''with respect to the index''.
| |
| Now amend the commit:
| |
| | |
| $ git commit --amend
| |
| $ git status
| |
| # On branch master
| |
| # Your branch is ahead of 'origin/master' by 1 commit.
| |
| #
| |
| # Changed but not updated:
| |
| # (use "git add <file>..." to update what will be committed)
| |
| # (use "git checkout -- <file>..." to discard changes in working directory)
| |
| #
| |
| # modified: VTK
| |
| #
| |
| no changes added to commit (use "git add" and/or "git commit -a")
| |
| | |
| Now ParaView's HEAD refers to the same VTK as before our mistake.
| |
| The work tree is still modified relative to that because we never ran 'git submodule update'.
| |
| | |
| ==Commits inside VTK==
| |
| | |
| In order to make a change to ParaView that ''does'' involve VTK, first make sure that the VTK subdirectory is checked out to the version the current ParaView wants:
| |
| | |
| $ git submodule update VTK
| |
| | |
| Now we can work in VTK:
| |
| | |
| $ cd VTK
| |
| VTK$ git status
| |
| # Not currently on any branch.
| |
| nothing to commit (working directory clean)
| |
| VTK$ git branch
| |
| * (no branch)
| |
| master
| |
| | |
| Wait! VTK is on a detached head! What to do?
| |
| While it is possible to work and commit on a detached head, it is easier to create a local branch on which to work.
| |
| | |
| VTK$ git checkout -b mywork
| |
| Switched to a new branch 'mywork'
| |
| VTK$ git status
| |
| # On branch mywork
| |
| nothing to commit (working directory clean)
| |
| VTK$ git branch
| |
| master
| |
| * mywork
| |
| | |
| Now pretend you are working on VTK alone and make the change and commit.
| |
| See the [http://www.vtk.org/Wiki/VTK/Git VTK Git Wiki] for details on this.
| |
| It is okay to change ParaView files outside the VTK if necessary, but they will not be included in the commit to VTK.
| |
| | |
| When finished in VTK, go back up to work on ParaView:
| |
| | |
| VTK$ cd ..
| |
| $ git status
| |
| # On branch master
| |
| # Changed but not updated:
| |
| # (use "git add <file>..." to update what will be committed)
| |
| # (use "git checkout -- <file>..." to discard changes in working directory)
| |
| #
| |
| # modified: VTK
| |
| #
| |
| no changes added to commit (use "git add" and/or "git commit -a")
| |
| | |
| ParaView now sees that we've modified VTK. It doesn't know anything about what changes were made, just that the currently checked out version of VTK is different than that referenced by ParaView currently. Now we can stage the new version of VTK:
| |
| | |
| $ git add VTK
| |
| $ git status
| |
| # On branch master
| |
| # Changes to be committed:
| |
| # (use "git reset HEAD <file>..." to unstage)
| |
| #
| |
| # modified: VTK
| |
| #
| |
| | |
| If any ParaView files outside of VTK were changed as part of this work, stage them as well.
| |
| Then commit
| |
| | |
| $ git commit
| |
| Avoid ParaView crash in VTK ...
| |
| | |
| Be sure to mention in the commit message the purpose of the change to ParaView.
| |
| Don't just say "Updated VTK". Someone looking at history later already knows that VTK was updated just by looking at the list of changes in the commit!
| |
| If the change was a fix only to VTK, but that was needed to fix a bug in ParaView, then describe that bug and the fix in the message.
| |
| | |
| =Troubleshooting=
| |
| | |
| ==Firewall Blocks Port 9418==
| |
| | |
| Some institutions have firewalls that block Git's native protocol port 9418.
| |
| Use the "<code>url.<base>.insteadOf</code>" configuration option to map git URLs to http:
| |
| | |
| <pre>
| |
| $ git config --global url.http://paraview.org/.insteadOf git://paraview.org/
| |
| $ git config --global url.http://vtk.org/.insteadOf git://vtk.org/
| |
| </pre>
| |
| | |
| This tells Git to translate URLs under the hood by replacing prefixes.
| |
| After running these commands ''once'' in your home directory then you can just use the "<code>git://</code>" mentioned elsewhere on this page and git will use the http protocol automagically.
| |
| | |
| An alternative approach is to manually choose the http URLs:
| |
| | |
| <pre>
| |
| $ git clone http://paraview.org/ParaView.git
| |
| $ cd ParaView
| |
| $ git submodule init
| |
| $ edit .git/config
| |
| (replace git:// with http:// in the submodule URLs)
| |
| $ git submodule update
| |
| </pre>
| |
| | |
| ==Git Below 1.6.5==
| |
| | |
| To clone ParaView using Git 1.6.4 or lower, use the commands
| |
| | |
| $ git clone git://paraview.org/ParaView.git
| |
| $ cd ParaView
| |
| $ git submodule init
| |
| $ git submodule update
| |
