View source for Screenshots: Working with clients for Mercurial

{{toc numerate=1}}

First install Mercurial and TortoiseHg. 

=== Initialize Repository ====
==== Command Line ==
With //hg init// you create a new repository.  

  * Your project folder ##/project## containing your wackowiki folder /wacko and source files is called Working Directory. 
  * Mercurial adds subdirectory ##/project/.hg## in your project folder. This new subdirectory is your new Repository, where all version data is kept. 

%%
$ cd /project 
$ hg init
%% 


==== TortoiseHg Workbench ====
Your new repository will be added to the Registry of your TortoiseHg workbench.

**1. Step:**
Open ~TortoiseHg: File > New Repository
file:/tortoisehg_create_new_repository.png

**2. Step:**
Provide destination path to your project and create project repository.
file:/tortoisehg_workbench_init_new_repository.png

**View**
Commit Dialog: Toolbars, Repository Registry, graph pane, file list pane with four columns, 
file:/tortoisehg_explorer_init_new_repository.png


=== Add files ===
==== Command Line ==
Mercurial does not work with files unless you tell it to manage them. To do that use the add command.
With //hg add// you add tracking of existing files to your new repository.   

  * all your files existing in folder: ##/project/wacko## will be introduced to new repository
  * /project/.hg/dirstate will be added
  * the entry in the output of //hg status// changes from “?” to “A”

%%
$ hg add
%%


==== TortoiseHg Workbench ====
To add files, select them in explorer.  To select all files use [Ctrl]+A. 
Then right click and select + Add in the context menu. 

**View**
Commit dialog: 
file:/tortoisehg_explorer_add_files_to_repository.png


=== Initial Commit  ====
==== Command Line ==
With //hg commit// you create a new changeset. 

  * enter a commit message
  * //hg status// will have remove added files from output

%%
$ hg commit -m "inital commit to new repository"
%%


==== TortoiseHg Workbench ====
Now you need to check in all files. Use the checkbox up top ( ~#### filter text ~#### ) to select all files. 
By clicking the commit button in the explorer, you will be asked to enter a commit message. 

**View** 
Commit Dialog:
file:/tortoisehg_explorer_initial_commit.png


=== Clone given branch ===
==== Command Line ==
With //hg clone//, you easily make an identical (local) copy of a repository. 
  * /project/.hg added to project root directory (new or existing)
  * for basic configuration you might want to add and edit ##~/project/.hg/hgrc##

%%
$ cd /project (e.g. /home/user/WackoWiki/wacko-dev)
$ hg clone https://bitbucket.org/wackowiki/wackowiki-dev ./WackoWiki/wacko-dev
%%


==== TortoiseHg Workbench ====
~TortoiseHg: File > Clone Repository

file:/tortoisehg_clone_repository_step1.png

**2. Step**
Source:    ##~https://bitbucket.org/wackowiki/wackowiki-dev##     ++(latest Development Version of WackoWiki)++
Destination:     ##./WackoWiki/wacko-dev##     ++(local WackoWiki project folder)++

file:/tortoisehg_clone_repository_step2.png

You should now have a local project directory (// /home/username/WackoWiki/wacko-dev //). 
Further Reading: ((http://hgbook.red-bean.com/read/a-tour-of-mercurial-the-basics.html#id345120 Mercurial: The Definitive Guide - Working with a repository))


file:/tortoisehg_clone_repository_step4.png


=== Configuration ===
Create a Mercurial Configuration file 

  * /project/##.hgrc##
  * ((/Org/Tools/Repository/Doc/HowTos#h1474-3 Configure mercurial))


=== Pull and update ===
With hg pull you will easily download just the latest code changes.

**1. Step:**
Check for changes
file:/tortoisehg_pull_changes_sync_toolbar1.png

file:/tortoisehg_pull_changes_step1.png

**2. Step:**
Pull changes
file:/tortoisehg_pull_changes_sync_toolbar2.png

file:/tortoisehg_pull_changes_step2.png


**3. Step:**
Update local repository
file:/tortoisehg_pull_changes_edit_toolbar.png

file:/tortoisehg_pull_changes_step3.png

file:/tortoisehg_pull_changes_step4.png

=== Committing changes ===
With hg commit making changes to your local repository is easy. 

**1. Step**
Make your edits. 

**2. Step**
(Re)Open TortoiseHg or refresh current repository. Commit your changes. 
file:/tortoisehg_commit_changes_task_toolbar.png


=== Commit and Push ===
Check repository settings.
file:/tortoisehg_syncronize_task_toolbar.png

~file:/tortoisehg_repository_settings_define_path.png
++Or find and edit your ##Mercurial.ini## on Windows, ##/.hgrc## on Unix, or ##.hg/hgrc## inside a repo. ((/Org/Tools/Repository/Doc/HowTos#h1474-5))++

Use two clones. Work in clone "main", push and merge in clone "sync", and pull back into clone "main".
((/Org/Tools/Repository/Doc/Workflow/SharedRepositoryModel Shared Repository Model))

  * ##~/project/.hgignore## can be used to exclude files from any command on the Working Directory
  * /WackoWiki/project/wacko (/home/user/WackoWiki/wackowiki-dev/wacko)

=== Links ==
  * http://tortoisehg.readthedocs.io/en/latest/quick.html
  * https://tortoisehg.bitbucket.io/manual/1.0/quick.html
  * http://hgbook.red-bean.com/

===ToDo==
  * description of Windows Explorer context menu 
  * description of configuration file .hgrc 
  * description of hg-git plugin