These functions make setup and use of source control with Sage easier, using the distributed Mercurial HG source control system. To learn about Mercurial, see http://www.selenic.com/mercurial/wiki/, in particular http://mercurial.selenic.com/wiki/UnderstandingMercurial. See also the Sage Developer’s Guide and http://wiki.sagemath.org/MercurialQueues for information about using Mercurial with Sage.
Some useful commands:
If you want to use Mercurial queues, then type hg_sage.q[TAB] to see the list of available methods. Indeed, many Mercurial commands are provided by methods here – type hg_sage.[TAB] to get a full list – and you can execute any Mercurial command using hg_sage(COMMAND). Finally, as listed, the above commands deal with the Mercurial repository for the Sage library. If you want to work with other repositories distributed with Sage, this file provides the following – replace “hg_sage” with each of the following commands to work with the given repository:
INPUT:
TESTS:
sage: 'scripts' in hg_scripts.__doc__
True
Add the given list of files (or file) or directories to your HG repository. They must exist already.
To see a list of files that haven’t been added to the repository do self.status(). They will appear with an explanation point next them.
Add needs to be called whenever you add a new file or directory to your project. Of course, it also needs to be called when you first create the project, to let hg know which files should be kept track of.
INPUT:
EXAMPLES:
sage: hg_sage.add('module_list.pyc', options='--dry-run')
Adding file module_list.pyc
cd ... && sage --hg add --dry-run "module_list.pyc"
Apply patches from a hg patch to the repository.
If the bundle is a .patch file, instead call the import_patch() method. To see what is in a bundle before applying it, using self.incoming(bundle).
INPUT:
EXAMPLES:
sage: hg_sage.unbundle('myhg.bundle') # not tested
Start a web server for this repository.
This server allows you to browse all files in the repository, see their changelogs, see who wrote any given line, etc.
INPUT:
EXAMPLES:
sage: hg_sage.serve() # not tested
Create an hg changeset bundle with the given filename against the repository at the given url (which is by default the ‘official’ Sage repository, unless push_url() is changed in a setup file).
If you have internet access, it’s best to just do hg_sage.bundle(filename). If you don’t find a revision r that you and the person unbundling both have (by looking at hg_sage.log()), then do hg_sage.bundle(filename, base=r).
Use hg_sage.inspect('file.bundle') to inspect the resulting bundle.
This is a file that you could post to a web page. However, Sage now typically accepts only patch files at its Trac server. The file will be written to the current directory.
INPUT:
EXAMPLES:
sage: hg_sage.bundle('new-bundle') # not tested
Writing to /.../new-bundle.hg
cd ... && sage --hg bundle tmphg http://hg.sagemath.org/sage-main/
searching for changes
133 changesets found
Successfully created hg patch bundle /.../new-bundle.hg
Display the change log for this repository. This is a list of changesets ordered by revision number.
By default this command outputs: changeset id and hash, tags, non-trivial parents, user, date and time, and a summary for each commit.
INPUT:
EXAMPLES:
sage: hg_sage.log() # not tested
cd ... && sage --hg log --config pager.pager="LESS='R' less"
...
update or merge working directory
Update the working directory to the specified revision.
If there are no outstanding changes in the working directory and there is a linear relationship between the current version and the requested version, the result is the requested version.
To merge the working directory with another revision, use the merge command.
By default, update will refuse to run if doing so would require merging or discarding local changes.
aliases: up, checkout, co
INPUT:
options - string (default: ‘’):
-C --clean overwrite locally modified files
-d --date tipmost revision matching date
-r --rev revision
debug - if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.update() # not tested
cd ... && sage --hg update
Commit your changes to the repository.
Quit out of the editor without saving to not record your changes.
INPUT:
files - space separated string of file names (optional) If specified only those files are committed. The path must be absolute or relative to self.dir().
it you will be dumped into an editor. If you’re using the Sage notebook, you must specify a comment.
options - string:
-A --addremove mark new/missing files as added/removed before committing
-m --message use <text> as commit message
-l --logfile read the commit message from <file>
-d --date record datecode as commit date
-u --user record user as committer
-I --include include names matching the given patterns
-X --exclude exclude names matching the given patterns
diff - (default: True) if True show diffs between your repository and your working repository before recording changes.
debug - if True, print the full system command being executed.
Note
If you create new files you should first add them with the add method.
EXAMPLES:
sage: hg_sage.commit('hg.py', comment='miscellaneous fixes') # not tested
cd ... && sage --hg commit -m "miscellaneous fixes" hg.py
Clone the current branch of the Sage library, and make it active.
Only available for the hg_sage repository.
Use hg_sage.switch('branch_name') to switch to a different branch. You must restart Sage after switching.
INPUT:
If rev is None, clones the latest recorded version of the repository. This is very fast, e.g., about 30-60 seconds (including any build). If a specific revision is specified, cloning may take much longer (e.g., 5 minutes), since all Pyrex code has to be regenerated and compiled.
EXAMPLES:
Make a clone of the repository called testing. A copy of the current repository will be created in a directory sage-testing, then SAGE_ROOT/devel/sage will point to sage-testing, and when you next restart Sage that’s the version you’ll be using.
sage: hg_sage.clone('testing') # not tested
...
Make a clone of the repository as it was at revision 1328.
sage: hg_sage.clone('testing', 1328) # not tested
...
update or merge working directory
Update the working directory to the specified revision.
If there are no outstanding changes in the working directory and there is a linear relationship between the current version and the requested version, the result is the requested version.
To merge the working directory with another revision, use the merge command.
By default, update will refuse to run if doing so would require merging or discarding local changes.
aliases: up, checkout, co
INPUT:
options - string (default: ‘’):
-C --clean overwrite locally modified files
-d --date tipmost revision matching date
-r --rev revision
debug - if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.update() # not tested
cd ... && sage --hg update
Commit your changes to the repository.
Quit out of the editor without saving to not record your changes.
INPUT:
files - space separated string of file names (optional) If specified only those files are committed. The path must be absolute or relative to self.dir().
it you will be dumped into an editor. If you’re using the Sage notebook, you must specify a comment.
options - string:
-A --addremove mark new/missing files as added/removed before committing
-m --message use <text> as commit message
-l --logfile read the commit message from <file>
-d --date record datecode as commit date
-u --user record user as committer
-I --include include names matching the given patterns
-X --exclude exclude names matching the given patterns
diff - (default: True) if True show diffs between your repository and your working repository before recording changes.
debug - if True, print the full system command being executed.
Note
If you create new files you should first add them with the add method.
EXAMPLES:
sage: hg_sage.commit('hg.py', comment='miscellaneous fixes') # not tested
cd ... && sage --hg commit -m "miscellaneous fixes" hg.py
Prints the current branch in the main Sage library.
If print_flag is True, the default, then print the message “The current branch is NAME”. If False, return the string NAME.
Warning
This prints the current branch for the main Sage library repository, even if you call a command like “hg_scripts.current_branch()” which refers to a different repository.
EXAMPLES:
sage: hg_sage.current_branch()
The current branch is: ...
Show differences between revisions for the specified files as a unified diff.
By default this command tells you exactly what you have changed in your working repository since you last committed changes.
INPUT:
files - space separated list of files (relative to self.dir())
rev - None or a list of integers.
options – string (default ‘’). Some possibilities:
-a --text treat all files as text
-g --git use git extended diff format
-p --show-function show which function each change is in
-I --include PATTERN [+] include names matching the given patterns
-X --exclude PATTERN [+] exclude names matching the given patterns
debug - boolean (default True); if True, print the full system command being executed.
Differences between files are shown using the unified diff format.
When two revision arguments are given, then changes are shown between those revisions. If only one revision is specified then that revision is compared to the working directory, and, when no revisions are specified, the working directory files are compared to its parent.
EXAMPLES:
sage: hg_sage.diff() # not tested
cd ... && sage --hg diff --config pager.pager="LESS='R' less"
To see the changes in this file since revision 10000:
sage: hg_sage.diff('sage/misc/hg.py', rev=10000) # not tested
cd ... && sage --hg diff -r 10000 sage/misc/hg.py --config pager.pager="LESS='R' less"
...
Return the directory where this repository is located.
EXAMPLES:
sage: os.path.realpath(hg_sage.dir()).startswith(os.path.realpath(os.environ['SAGE_ROOT']))
True
Export patches with the changeset header and diffs for one or more revisions.
If multiple revisions are given, one plain text unified diff file is generated for each one. These files should be applied using import_patch in order from smallest to largest revision number. The information shown in the changeset header is: author, changeset hash, parent and commit comment.
Note
If you are sending a patch to somebody using export and it depends on previous patches, make sure to include those revisions too! Alternatively, use the bundle() method, which includes enough information to patch against the default repository (but is an annoying and mysterious binary file).
INPUT:
revs - integer or list of integers (revision numbers); use the log() method to see these numbers.
filename - (default: ‘%R.patch’) The name of the file is given using a format string. The formatting rules are as follows:
%% literal "%" character
%H changeset hash (40 bytes of hexadecimal)
%N number of patches being generated
%R changeset revision number
%b basename of the exporting repository
%h short-form changeset hash (12 bytes of hexadecimal)
%n zero-padded sequence number, starting at 1
%r zero-padded changeset revision number
text - boolean (default False). Setting this to be True has the same effect as passing the “-a” option below.
options - string (default: ‘’)
Without the -a option, export will avoid generating diffs of files it detects as binary. With -a, export will generate a diff anyway, probably with undesirable results.
With the --switch-parent option, the diff will be against the second parent. It can be useful to review a merge.
debug - boolean (default True); if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.export('tip') # not tested
sage: hg_sage.export('tip', 'new.patch') # not tested
sage: hg_sage.export('tip', 'new.patch', options='--a') # not tested
Show all repository head changesets.
Repository “heads” are changesets that don’t have children changesets. They are where development generally takes place and are the usual targets for update and merge operations.
INPUT:
options - string (default: ‘’):
-r --rev show only heads which are descendants of rev
--style display using template map file
--template display with template
debug - if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.head() # random
cd ... && sage --hg head
changeset: 15825:6ca08864b80c
tag: tip
user: Jeroen Demeyer <jdemeyer@cage.ugent.be>
date: Tue Jun 07 12:31:57 2011 +0000
summary: 4.7.1.alpha2
Show all repository head changesets.
Repository “heads” are changesets that don’t have children changesets. They are where development generally takes place and are the usual targets for update and merge operations.
INPUT:
options - string (default: ‘’):
-r --rev show only heads which are descendants of rev
--style display using template map file
--template display with template
debug - if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.head() # random
cd ... && sage --hg head
changeset: 15825:6ca08864b80c
tag: tip
user: Jeroen Demeyer <jdemeyer@cage.ugent.be>
date: Tue Jun 07 12:31:57 2011 +0000
summary: 4.7.1.alpha2
Print a help message about cmd, or if cmd is omitted, print a general Mercurial help message.
If debug is True, also print the full system command being executed.
If this hg object is called hg_sage, then you call a command using hg_sage('usual hg command line notation'). Type “hg_sage?” for more information.
EXAMPLES:
sage: hg_sage.help() # not tested
Mercurial Distributed SCM
list of commands:
...
sage: hg_sage.help('status') # not tested
hg status [OPTION]... [FILE]...
aliases: st
show changed files in the working directory
...
Display the change log for this repository. This is a list of changesets ordered by revision number.
By default this command outputs: changeset id and hash, tags, non-trivial parents, user, date and time, and a summary for each commit.
INPUT:
EXAMPLES:
sage: hg_sage.log() # not tested
cd ... && sage --hg log --config pager.pager="LESS='R' less"
...
Import an ordered set of patches from patch file, i.e., a plain text file created using the export command.
If there are outstanding changes in the working directory, import_patch will abort unless given the -f flag.
If imported patch was generated by the export command, user and description from patch override values from message headers and body. Values given as options with -m and -u override these.
INPUT:
filename - string
options - string (default: ‘’):
options: [-p NUM] [-b BASE] [-m MESSage] [-f] PATCH...
-p --strip NUM directory strip option for patch. This has
the same meaning as the corresponding patch
option (default: 1)
-b --base PATH base path
-f --force skip check for outstanding uncommitted changes
--no-commit don't commit, just update the working directory
--exact apply patch to the nodes from which it was
generated
--import-branch use any branch information in patch (implied
by --exact)
-m --message TEXT use text as commit message
-l --logfile FILE read commit message from file
-d --date DATE record the specified date as commit date
-u --user USER record the specified user as committer
-s --similarity SIMILARITY guess renamed files by similarity (0<=s<=100)
--mq operate on patch repository
debug - boolean (default True); if True, print the full system command being executed.
ALIASES: patch
EXAMPLES:
sage: hg_sage.import_patch('trac_2001.patch') # not tested
Show new changesets found in the given source and display the corresponding diffs. This even works if the source is a bundle file (ends in .hg or .bundle). This is great because it lets you “see inside” the mysterious binary-only .hg files.
Show new changesets found in the specified path/URL or the default pull location. These are the changesets that would be pulled if a pull was requested.
For remote repository, using -bundle avoids downloading the changesets twice if the incoming is followed by a pull.
See pull for valid source format details.
ALIAS: inspect
INPUT:
filename - string, may be a URL
options - (default: ‘-p’):
string '[-p] [-n] [-M] [-r REV] ...'
-M --no-merges do not show merges
-f --force run even when remote repository is unrelated
--style display using template map file
-n --newest-first show newest record first
--bundle file to store the bundles into
-p --patch show patch
-r --rev a specific revision you would like to pull
--template display with template
-e --ssh specify ssh command to use
--remotecmd specify hg command to run on the remote side
debug - boolean (default True); if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.incoming("http://hg.sagemath.org/sage-main") # not tested
cd ... && sage --hg incoming "http://hg.sagemath.org/sage-main" --config pager.pager="LESS='R' less"
comparing with http://hg.sagemath.org/sage-main
searching for changes
no changes found
Show new changesets found in the given source and display the corresponding diffs. This even works if the source is a bundle file (ends in .hg or .bundle). This is great because it lets you “see inside” the mysterious binary-only .hg files.
Show new changesets found in the specified path/URL or the default pull location. These are the changesets that would be pulled if a pull was requested.
For remote repository, using -bundle avoids downloading the changesets twice if the incoming is followed by a pull.
See pull for valid source format details.
ALIAS: inspect
INPUT:
filename - string, may be a URL
options - (default: ‘-p’):
string '[-p] [-n] [-M] [-r REV] ...'
-M --no-merges do not show merges
-f --force run even when remote repository is unrelated
--style display using template map file
-n --newest-first show newest record first
--bundle file to store the bundles into
-p --patch show patch
-r --rev a specific revision you would like to pull
--template display with template
-e --ssh specify ssh command to use
--remotecmd specify hg command to run on the remote side
debug - boolean (default True); if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.incoming("http://hg.sagemath.org/sage-main") # not tested
cd ... && sage --hg incoming "http://hg.sagemath.org/sage-main" --config pager.pager="LESS='R' less"
comparing with http://hg.sagemath.org/sage-main
searching for changes
no changes found
Print all branches in the current Sage installation.
If print_flag is True, the default, then print the message “Branches found:”, followed by a list of the branches. If False, return the list of the names of the branches.
Warning
This lists the branches for the main Sage library repository, even if you call a command like “hg_scripts.list_branches()” which refers to a different repository.
EXAMPLES:
sage: hg_sage.list_branches()
Branches found:
...
sage: 'main' in hg_sage.list_branches(print_flag=False)
True
Display the change log for this repository. This is a list of changesets ordered by revision number.
By default this command outputs: changeset id and hash, tags, non-trivial parents, user, date and time, and a summary for each commit.
INPUT:
EXAMPLES:
sage: hg_sage.log() # not tested
cd ... && sage --hg log --config pager.pager="LESS='R' less"
...
Merge working directory with another revision
Merge the contents of the current working directory and the requested revision. Files that changed between either parent are marked as changed for the next commit and a commit must be performed before any further updates are allowed.
INPUT:
options - default: ‘’:
-f --force force a merge with outstanding changes
-r --rev revision to merge
debug - if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.merge() # not tested
cd ... && sage --hg merge
Move (rename) the given file, from src to dest. This command takes effect in the next commit.
INPUT:
src, dest - strings that define a file, relative to self.dir()
options:
-A --after record a rename that has already occurred
-f --force forcibly copy over an existing managed file
-n --dry-run do not perform actions, just print output
debug - boolean (default True); if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.rename('sage/misc/hg.py', 'sage/misc/hgnew.py', options='--dry-run') # random because locking might fail
Moving sage/misc/hg.py --> sage/misc/hgnew.py
cd ... && sage --hg mv --dry-run "sage/misc/hg.py" "sage/misc/hgnew.py"
Move (rename) the given file, from src to dest. This command takes effect in the next commit.
INPUT:
src, dest - strings that define a file, relative to self.dir()
options:
-A --after record a rename that has already occurred
-f --force forcibly copy over an existing managed file
-n --dry-run do not perform actions, just print output
debug - boolean (default True); if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.rename('sage/misc/hg.py', 'sage/misc/hgnew.py', options='--dry-run') # random because locking might fail
Moving sage/misc/hg.py --> sage/misc/hgnew.py
cd ... && sage --hg mv --dry-run "sage/misc/hg.py" "sage/misc/hgnew.py"
Use this to find changsets that are in your branch, but not in the specified destination repository. If no destination is specified, the official repository is used. By default, push_url() is used.
From the Mercurial documentation:
Show changesets not found in the specified destination repository or the default push location. These are the changesets that would be pushed if a push was requested.
See push() for valid destination format details.
INPUT:
url - (Default: push_url()) the official repository
options - (Default: None):
-M --no-merges do not show merges
-f --force run even when remote repository is unrelated
-p --patch show patch
--style display using template map file
-r --rev a specific revision you would like to push
-n --newest-first show newest record first
--template display with template
-e --ssh specify ssh command to use
--remotecmd specify hg command to run on the remote side
debug - if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.outgoing() # not tested
cd ... && sage --hg outgoing http://hg.sagemath.org/sage-main/ --config pager.pager="LESS='R' less"
comparing with http://hg.sagemath.org/sage-main/
searching for changes
...
Import an ordered set of patches from patch file, i.e., a plain text file created using the export command.
If there are outstanding changes in the working directory, import_patch will abort unless given the -f flag.
If imported patch was generated by the export command, user and description from patch override values from message headers and body. Values given as options with -m and -u override these.
INPUT:
filename - string
options - string (default: ‘’):
options: [-p NUM] [-b BASE] [-m MESSage] [-f] PATCH...
-p --strip NUM directory strip option for patch. This has
the same meaning as the corresponding patch
option (default: 1)
-b --base PATH base path
-f --force skip check for outstanding uncommitted changes
--no-commit don't commit, just update the working directory
--exact apply patch to the nodes from which it was
generated
--import-branch use any branch information in patch (implied
by --exact)
-m --message TEXT use text as commit message
-l --logfile FILE read commit message from file
-d --date DATE record the specified date as commit date
-u --user USER record the specified user as committer
-s --similarity SIMILARITY guess renamed files by similarity (0<=s<=100)
--mq operate on patch repository
debug - boolean (default True); if True, print the full system command being executed.
ALIASES: patch
EXAMPLES:
sage: hg_sage.import_patch('trac_2001.patch') # not tested
Pull all new patches from the repository at the given url, or use the default ‘official’ repository if no url is specified.
INPUT:
url - (Default: pull_url()) the official repository
options - (Default: ‘-u’):
-u --update update the working directory to tip after pull
-e --ssh specify ssh command to use
-f --force run even when remote repository is unrelated
-r --rev a specific revision you would like to pull
--remotecmd specify hg command to run on the remote side
debug - if True, print the full system command being executed.
Some notes about using SSH with Mercurial:
SSH requires an accessible shell account on the destination machine and a copy of hg in the remote path or specified with as remotecmd.
path is relative to the remote user’s home directory by default. Use an extra slash at the start of a path to specify an absolute path: ssh://example.com//tmp/repository
Mercurial doesn’t use its own compression via SSH; the right thing to do is to configure it in your /.ssh/ssh_config, e.g.:
Host *.mylocalnetwork.example.com
Compression off
Host *
Compression on
Alternatively specify ‘ssh -C’ as your ssh command in your hgrc or with the -ssh command line option.
EXAMPLES:
sage: hg_sage.pull() # not tested
cd ... && sage --hg pull http://hg.sagemath.org/sage-main/
...
Return the default ‘master url’ for this repository.
EXAMPLES:
sage: hg_sage.pull_url()
'http://hg.sagemath.org/sage-main/'
Push all new patches from the repository to the given destination.
INPUT:
url - (Default: push_url()) the official repository
options - (Default: ‘’):
-e --ssh specify ssh command to use
-f --force run even when remote repository is unrelated
-r --rev a specific revision you would like to pull
--remotecmd specify hg command to run on the remote side
debug - if True, print the full system command being executed.
Some notes about using SSH with Mercurial:
SSH requires an accessible shell account on the destination machine and a copy of hg in the remote path or specified with as remotecmd.
path is relative to the remote user’s home directory by default. Use an extra slash at the start of a path to specify an absolute path: ssh://example.com//tmp/repository
Mercurial doesn’t use its own compression via SSH; the right thing to do is to configure it in your /.ssh/ssh_config, e.g.:
Host *.mylocalnetwork.example.com
Compression off
Host *
Compression on
Alternatively specify ‘ssh -C’ as your ssh command in your hgrc or with the -ssh command line option.
EXAMPLES:
sage: hg_sage.push() # not tested
cd ... && sage --hg push http://hg.sagemath.org/sage-main/
...
Return the default url for uploading this repository.
EXAMPLES:
sage: hg_sage.push_url()
'http://hg.sagemath.org/sage-main/'
Mercurial queues: print the patches in the queue which have been applied.
If optional argument verbose is True, then also print the first line of each patch’s header.
If debug is True, also print the full system command being executed.
EXAMPLES:
sage: hg_sage.qapplied()
cd ... && sage --hg qapplied...
Mercurial queues: delete the named patch from the queue.
INPUT:
EXAMPLES:
sage: hg_sage.qdelete('old.patch new.patch') # not tested
cd ... && sage --hg qdelete old.patch new.patch ...
Mercurial queues: show a diff including the current patch and any more recent changes, thus showing what the current patch would become after qrefresh().
Use diff() if you only want to see the changes made since the last qrefresh().
INPUT:
options – string (default ‘’). Some possibilities:
-a --text treat all files as text
-g --git use git extended diff format
-p --show-function show which function each change is in
-I --include PATTERN [+] include names matching the given patterns
-X --exclude PATTERN [+] exclude names matching the given patterns
debug – (default True): if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.qdiff() # not tested
cd ... && sage --hg qdiff ...
Mercurial queues: insert the patch from filename in the queue.
INPUT:
filename – string
options – string (default ‘’):
-e --existing import file in patch directory
-n --name NAME name of patch file
-f --force overwrite existing files
-r --rev REV [+] place existing revisions under mq control
-g --git use git extended diff format
-P --push qpush after importing
debug – (default True): if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.qimport('old.patch') # not tested
cd ... && sage --hg qimport old.patch ...
Mercurial queues: create a new patch.
INPUT:
patch – string, the name of the patch.
options – string (default ‘’). Some possibilities:
-e --edit edit commit message
-g --git use git extended diff format
-I --include PATTERN [+] include names matching the given patterns
-X --exclude PATTERN [+] exclude names matching the given patterns
-m --message TEXT use text as commit message
debug – (default True): if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.qnew('my_new.patch') # not tested
cd ... && sage --hg qnew my_new.patch
Mercurial queues: pop the top of the patch stack, or if given a patch, pop patches off of the stack until it is at the top.
INPUT:
EXAMPLES:
sage: hg_sage.qpop() # not tested
cd ... && sage --hg qpop
Mercurial queues: push the next patch onto the stack.
INPUT:
EXAMPLES:
sage: hg_sage.qpush() # not tested
cd ... && sage --hg qpush
Mercurial queues: update the current patch.
INPUT:
options – string (default ‘’). Some possibilities:
-e --edit edit commit message
-g --git use git extended diff format
-I --include PATTERN [+] include names matching the given patterns
-X --exclude PATTERN [+] exclude names matching the given patterns
-m --message TEXT use text as commit message
debug – (default True): if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.qrefresh() # not tested
cd ... && sage --hg qrefresh
Mercurial queues: delete the named patch from the queue.
INPUT:
EXAMPLES:
sage: hg_sage.qdelete('old.patch new.patch') # not tested
cd ... && sage --hg qdelete old.patch new.patch ...
Mercurial queues: print the series file.
If optional argument verbose is True, then also print the first line of each patch’s header.
If debug is True, also print the full system command being executed.
EXAMPLES:
sage: hg_sage.qseries()
cd ... && sage --hg qseries...
Mercurial queues: print the patches in the queue which have not yet been applied.
If optional argument verbose is True, then also print the first line of each patch’s header.
If debug is True, also print the full system command being executed.
EXAMPLES:
sage: hg_sage.qunapplied()
cd ... && sage --hg qunapplied...
Commit your changes to the repository.
Quit out of the editor without saving to not record your changes.
INPUT:
files - space separated string of file names (optional) If specified only those files are committed. The path must be absolute or relative to self.dir().
it you will be dumped into an editor. If you’re using the Sage notebook, you must specify a comment.
options - string:
-A --addremove mark new/missing files as added/removed before committing
-m --message use <text> as commit message
-l --logfile read the commit message from <file>
-d --date record datecode as commit date
-u --user record user as committer
-I --include include names matching the given patterns
-X --exclude exclude names matching the given patterns
diff - (default: True) if True show diffs between your repository and your working repository before recording changes.
debug - if True, print the full system command being executed.
Note
If you create new files you should first add them with the add method.
EXAMPLES:
sage: hg_sage.commit('hg.py', comment='miscellaneous fixes') # not tested
cd ... && sage --hg commit -m "miscellaneous fixes" hg.py
Remove the given list of files (or file) or directories from your HG repository.
INPUT:
EXAMPLES:
sage: hg_sage.remove('sage/misc/remove_me.py') # not tested
Removing file sage/misc/remove_me.py
cd ... && sage --hg rm "sage/misc/remove_me.py"
Move (rename) the given file, from src to dest. This command takes effect in the next commit.
INPUT:
src, dest - strings that define a file, relative to self.dir()
options:
-A --after record a rename that has already occurred
-f --force forcibly copy over an existing managed file
-n --dry-run do not perform actions, just print output
debug - boolean (default True); if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.rename('sage/misc/hg.py', 'sage/misc/hgnew.py', options='--dry-run') # random because locking might fail
Moving sage/misc/hg.py --> sage/misc/hgnew.py
cd ... && sage --hg mv --dry-run "sage/misc/hg.py" "sage/misc/hgnew.py"
Revert files or dirs to their states as of some revision.
Note
This command is most likely not what you are looking for. revert will partially overwrite content in the working directory without changing the working directory parents. Use the method update(options='-r REV') to check out earlier revisions, or update(options='--clean .') to undo a merge which has added another parent.
With no revision specified, revert the named files or directories to the contents they had in the parent of the working directory. This restores the contents of the affected files to an unmodified state and unschedules adds, removes, copies, and renames. If the working directory has two parents, you must explicitly specify a revision.
Using the rev argument, revert the given files or directories to their contents as of a specific revision. This can be helpful to “roll back” some or all of an earlier change. Run hg_sage('help dates') for a list of formats valid for the -d/--date option.
Revert modifies the working directory. It does not commit any changes, or change the parent of the working directory. If you revert to a revision other than the parent of the working directory, the reverted files will thus appear modified afterwards.
If a file has been deleted, it is restored. If the executable mode of a file was changed, it is reset.
If names are given, all files matching the names are reverted. If no arguments are given, no files are reverted. To revert all files in the repository, pass the argument options='--all'.
Modified files are saved with a .orig suffix before reverting. To disable these backups, use options='--no-backup'.
If debug is True, also print the full system command being executed.
OPTIONS:
-a --all revert all changes when no arguments given
-d --date DATE tipmost revision matching date
--no-backup do not save backup copies of files
-I --include PATTERN [+] include names matching the given patterns
-X --exclude PATTERN [+] exclude names matching the given patterns
-n --dry-run do not perform actions, just print output
--mq operate on patch repository
EXAMPLES:
sage: hg_sage.revert('sage/misc/hg.py', rev=12000, options='--dry-run') # random because locking might fail
cd ... && sage --hg revert --dry-run -r 12000 sage/misc/hg.py
Remove the given list of files (or file) or directories from your HG repository.
INPUT:
EXAMPLES:
sage: hg_sage.remove('sage/misc/remove_me.py') # not tested
Removing file sage/misc/remove_me.py
cd ... && sage --hg rm "sage/misc/remove_me.py"
Remove recorded patches without changing the working copy.
If debug is True, also print the full system command being executed.
EXAMPLES:
sage: hg_sage.rollback() # not tested
cd ... && sage --hg rollback
Create an hg changeset bundle with the given filename against the repository at the given url (which is by default the ‘official’ Sage repository, unless push_url() is changed in a setup file).
If you have internet access, it’s best to just do hg_sage.bundle(filename). If you don’t find a revision r that you and the person unbundling both have (by looking at hg_sage.log()), then do hg_sage.bundle(filename, base=r).
Use hg_sage.inspect('file.bundle') to inspect the resulting bundle.
This is a file that you could post to a web page. However, Sage now typically accepts only patch files at its Trac server. The file will be written to the current directory.
INPUT:
EXAMPLES:
sage: hg_sage.bundle('new-bundle') # not tested
Writing to /.../new-bundle.hg
cd ... && sage --hg bundle tmphg http://hg.sagemath.org/sage-main/
searching for changes
133 changesets found
Successfully created hg patch bundle /.../new-bundle.hg
Create an hg changeset bundle with the given filename against the repository at the given url (which is by default the ‘official’ Sage repository, unless push_url() is changed in a setup file).
If you have internet access, it’s best to just do hg_sage.bundle(filename). If you don’t find a revision r that you and the person unbundling both have (by looking at hg_sage.log()), then do hg_sage.bundle(filename, base=r).
Use hg_sage.inspect('file.bundle') to inspect the resulting bundle.
This is a file that you could post to a web page. However, Sage now typically accepts only patch files at its Trac server. The file will be written to the current directory.
INPUT:
EXAMPLES:
sage: hg_sage.bundle('new-bundle') # not tested
Writing to /.../new-bundle.hg
cd ... && sage --hg bundle tmphg http://hg.sagemath.org/sage-main/
searching for changes
133 changesets found
Successfully created hg patch bundle /.../new-bundle.hg
Start a web server for this repository.
This server allows you to browse all files in the repository, see their changelogs, see who wrote any given line, etc.
INPUT:
EXAMPLES:
sage: hg_sage.serve() # not tested
Print the output of the command “hg status” for the repository.
If debug is True, also print the full system command being executed.
EXAMPLES:
sage: hg_sage.status()
Getting status of modified or unknown files:
cd ... && sage --hg status
...
sage: hg_sage.status(debug=False)
Getting status of modified or unknown files:
...
Switch to a different branch. You must restart Sage after switching.
Only available for hg_sage.
INPUT:
If the name is not given, this function returns a list of all branches.
EXAMPLES:
sage: hg_sage.switch() # random
['main']
sage: hg_sage.switch('new') # not tested
----------------------------------------------------------
Building and installing modified Sage library files.
...
Apply patches from a hg patch to the repository.
If the bundle is a .patch file, instead call the import_patch() method. To see what is in a bundle before applying it, using self.incoming(bundle).
INPUT:
EXAMPLES:
sage: hg_sage.unbundle('myhg.bundle') # not tested
update or merge working directory
Update the working directory to the specified revision.
If there are no outstanding changes in the working directory and there is a linear relationship between the current version and the requested version, the result is the requested version.
To merge the working directory with another revision, use the merge command.
By default, update will refuse to run if doing so would require merging or discarding local changes.
aliases: up, checkout, co
INPUT:
options - string (default: ‘’):
-C --clean overwrite locally modified files
-d --date tipmost revision matching date
-r --rev revision
debug - if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.update() # not tested
cd ... && sage --hg update
update or merge working directory
Update the working directory to the specified revision.
If there are no outstanding changes in the working directory and there is a linear relationship between the current version and the requested version, the result is the requested version.
To merge the working directory with another revision, use the merge command.
By default, update will refuse to run if doing so would require merging or discarding local changes.
aliases: up, checkout, co
INPUT:
options - string (default: ‘’):
-C --clean overwrite locally modified files
-d --date tipmost revision matching date
-r --rev revision
debug - if True, print the full system command being executed.
EXAMPLES:
sage: hg_sage.update() # not tested
cd ... && sage --hg update
Show differences between revisions for the specified files as a unified diff.
By default this command tells you exactly what you have changed in your working repository since you last committed changes.
INPUT:
files - space separated list of files (relative to self.dir())
rev - None or a list of integers.
options – string (default ‘’). Some possibilities:
-a --text treat all files as text
-g --git use git extended diff format
-p --show-function show which function each change is in
-I --include PATTERN [+] include names matching the given patterns
-X --exclude PATTERN [+] exclude names matching the given patterns
debug - boolean (default True); if True, print the full system command being executed.
Differences between files are shown using the unified diff format.
When two revision arguments are given, then changes are shown between those revisions. If only one revision is specified then that revision is compared to the working directory, and, when no revisions are specified, the working directory files are compared to its parent.
EXAMPLES:
sage: hg_sage.diff() # not tested
cd ... && sage --hg diff --config pager.pager="LESS='R' less"
To see the changes in this file since revision 10000:
sage: hg_sage.diff('sage/misc/hg.py', rev=10000) # not tested
cd ... && sage --hg diff -r 10000 sage/misc/hg.py --config pager.pager="LESS='R' less"
...
Color option for Mercurial.
This is empty when called from the command-line, and it disables the “color” extension when called from the notebook. According to the Mercurial docs, “color” is only used by the Mercurial commands diff, status, and qseries; however, it also seems to be used by a few other commands (like log, and qapplied, among others). This function is used in HG.diff(), HG.log(), HG.status(), HG.qdiff(), HG.qseries(), HG.qapplied(), and HG.qunapplied().
EXAMPLES:
sage: sage.server.support.EMBEDDED_MODE=False
sage: sage.misc.hg.color()
''
sage: sage.server.support.EMBEDDED_MODE=True
sage: sage.misc.hg.color()
'--config color.mode=off'
sage: sage.server.support.EMBEDDED_MODE=False
Wrap the get_remote_file method to move the file if it ends in ?stuff, as happens with funny URLs from web servers.
This is an HG (Mercurial) repository.
To learn about Mercurial, see http://www.selenic.com/mercurial/wiki/.
This system is fully usable from both the command line and the Sage notebook.
Most commands are directly provided as member functions. However, you can use the full functionality of hg, i.e.,
hg_extcode("command line arguments")
is exactly the same as typing:
cd /usr/share/sagemath/ext && hg command line arguments
This is an HG (Mercurial) repository.
To learn about Mercurial, see http://www.selenic.com/mercurial/wiki/.
This system is fully usable from both the command line and the Sage notebook.
Most commands are directly provided as member functions. However, you can use the full functionality of hg, i.e.,
hg_root("command line arguments")
is exactly the same as typing:
cd /usr/lib64/sagemath && hg command line arguments
This is an HG (Mercurial) repository.
To learn about Mercurial, see http://www.selenic.com/mercurial/wiki/.
This system is fully usable from both the command line and the Sage notebook.
Most commands are directly provided as member functions. However, you can use the full functionality of hg, i.e.,
hg_sage("command line arguments")
is exactly the same as typing:
cd /usr/lib64/sagemath/devel/sage && hg command line arguments
This is an HG (Mercurial) repository.
To learn about Mercurial, see http://www.selenic.com/mercurial/wiki/.
This system is fully usable from both the command line and the Sage notebook.
Most commands are directly provided as member functions. However, you can use the full functionality of hg, i.e.,
hg_sagenb("command line arguments")
is exactly the same as typing:
cd /usr/lib64/sagemath/devel/sagenb && hg command line arguments
This is an HG (Mercurial) repository.
To learn about Mercurial, see http://www.selenic.com/mercurial/wiki/.
This system is fully usable from both the command line and the Sage notebook.
Most commands are directly provided as member functions. However, you can use the full functionality of hg, i.e.,
hg_scripts("command line arguments")
is exactly the same as typing:
cd /usr/lib64/sagemath/local/bin && hg command line arguments
Return a pager program, either ‘cat’ or ‘less’: ‘cat’ if embedded in the notebook, ‘less’ otherwise.
It is returned as a string suitable for a config option for the ‘hg’ command.
EXAMPLES:
sage: sage.server.support.EMBEDDED_MODE=False
sage: sage.misc.hg.pager()
'--config pager.pager="LESS=\'R\' less"'
sage: sage.server.support.EMBEDDED_MODE=True
sage: sage.misc.hg.pager()
'--config pager.pager=cat'
sage: sage.server.support.EMBEDDED_MODE=False