Module: sage.misc.hg
SAGE Interface to the HG/Mercurial Revision Control System
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 UnderstandingMercurial .
This system should all be fully usable from the SAGE notebook (except for merging, currently). This system should all be mostly usable from the SAGE notebook.
hg_sage.record()
to record all of your changes.
hg_sage.bundle('filename')
to bundle them up to send them.
hg_sage.inspect('filename.hg')
to inspect a bundle.
hg_sage.unbundle('filename.hg')
to import a bundle into your
repository.
hg_sage.pull()
to synchronize with the latest official
stable SAGE changesets.
Module-level Functions
f) |
Wrap the get_remote_file method to move the file if it ends in ?stuff, as happens with funny urls from web servers.
) |
Return a page program, which is either cat or less at present.
Return cat if embedded in the notebook, and less otherwise.
Class: HG
To learn about Mercurial, see http://www.selenic.com/mercurial/wiki/.
This system should all be fully usable from 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 <SAGE_ROOT>/devel/sage/ \&\& hg command line arguments
self, dir, name, pull_url, push_url, [target=None], [cloneable=False], [obj_name=]) |
Input:
Functions: add,
apply,
browse,
bundle,
changes,
checkout,
ci,
clone,
co,
commit,
current_branch,
diff,
dir,
export,
head,
heads,
help,
history,
import_patch,
incoming,
inspect,
list_branches,
log,
merge,
move,
mv,
outgoing,
patch,
pull,
pull_url,
push,
push_url,
record,
remove,
rename,
revert,
rm,
rollback,
save,
send,
serve,
status,
switch,
unbundle,
up,
update,
what
self, files, [options=]) |
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:
self, bundle, [update=True], [options=]) |
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:
self, [port=8200], [address=localhost], [open_viewer=True], [options=]) |
Start a web server for this repository.
This server is very nice - you can browse all files in the repository, see their changelogs, see who wrote any given line, etc. Very nice.
Input:
self, filename, [options=], [url=None], [base=None], [to=None]) |
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 self.inspect('file.bundle') to inspect the resulting bundle.
This is a file that you should probably send to William Stein (wstein@gmail.com), post to a web page, or send to sage-devel. It will be written to the current directory.
Input:
self, [branches=None], [keyword=None], [limit=None], [rev=None], [merges=True], [only_merges=False], [patch=None], [template=False], [include=None], [exclude=None], [verbose=False]) |
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:
self, [options=]) |
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:
self, [files=], [comment=None], [options=], [diff=True]) |
Commit your changes to the repository.
Quit out of the editor without saving to not record your changes.
Input:
comment - optional changeset comment. If you don't give 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 commiter -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.
Note: If you create new files you should first add them with the add method.
self, name, [rev=None]) |
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.
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 ...
self, [options=]) |
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:
self, [files=], [comment=None], [options=], [diff=True]) |
Commit your changes to the repository.
Quit out of the editor without saving to not record your changes.
Input:
comment - optional changeset comment. If you don't give 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 commiter -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.
Note: If you create new files you should first add them with the add method.
self, [print_flag=True]) |
Lists the current branch.
self, [files=], [rev=None]) |
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 commited changes.
Input:
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.
self) |
Return the directory where this repository is located.
self, revs, [filename=None], [text=False], [options=]) |
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:
self, [options=]) |
show current repository heads
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:
self, [options=]) |
show current repository heads
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:
self, [cmd=]) |
Return help about the given command, or if cmd is omitted a list of commands.
If this hg object is called hg_sage, then you
call a command using
hg_sage('usual hg command line notation')
self, [branches=None], [keyword=None], [limit=None], [rev=None], [merges=True], [only_merges=False], [patch=None], [template=False], [include=None], [exclude=None], [verbose=False]) |
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:
self, filename, [options=]) |
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 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:
ALIASES: patch
self, source, [options=-p]) |
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 myserious 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:
self, source, [options=-p]) |
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 myserious 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:
self, [print_flag=True]) |
Print all branches in the current SAGE installation.
self, [branches=None], [keyword=None], [limit=None], [rev=None], [merges=True], [only_merges=False], [patch=None], [template=False], [include=None], [exclude=None], [verbose=False]) |
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:
self, [options=]) |
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:
self, src, dest, [options=]) |
Move (rename) the given file, from src to dest. This command takes effect in the next commit.
Input:
self, src, dest, [options=]) |
Move (rename) the given file, from src to dest. This command takes effect in the next commit.
Input:
self, [url=None], [opts=]) |
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:
self, filename, [options=]) |
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 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:
ALIASES: patch
self, [url=None], [options=-u]) |
Pull all new patches from the repository at the given url, or use the default 'official' repository if no url is specified.
Input:
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.
self) |
Return the default 'master url' for this repository.
self, [url=None], [options=]) |
Push all new patches from the repository to the given destination.
Input:
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.
self) |
Return the default url for uploading this repository.
self, [files=], [comment=None], [options=], [diff=True]) |
Commit your changes to the repository.
Quit out of the editor without saving to not record your changes.
Input:
comment - optional changeset comment. If you don't give 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 commiter -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.
Note: If you create new files you should first add them with the add method.
self, files, [options=]) |
Remove the given list of files (or file) or directories from your HG repository.
Input:
self, src, dest, [options=]) |
Move (rename) the given file, from src to dest. This command takes effect in the next commit.
Input:
self, [files=], [options=], [rev=None]) |
Revert files or dirs to their states as of some revision
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. If the working directory has two parents, you must explicitly specify the revision to revert to.
Modified files are saved with a .orig suffix before reverting. To disable these backups, use -no-backup.
Using the -r option, 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 a change that should not have been committed.
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 recreated. 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, all files in the repository are reverted.
OPTIONS: -no-backup do not save backup copies of files -I -include include names matching given patterns -X -exclude exclude names matching given patterns -n -dry-run do not perform actions, just print output
self, files, [options=]) |
Remove the given list of files (or file) or directories from your HG repository.
Input:
self) |
Remove recorded patches without changing the working copy.
self, filename, [options=], [url=None], [base=None], [to=None]) |
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 self.inspect('file.bundle') to inspect the resulting bundle.
This is a file that you should probably send to William Stein (wstein@gmail.com), post to a web page, or send to sage-devel. It will be written to the current directory.
Input:
self, filename, [options=], [url=None], [base=None], [to=None]) |
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 self.inspect('file.bundle') to inspect the resulting bundle.
This is a file that you should probably send to William Stein (wstein@gmail.com), post to a web page, or send to sage-devel. It will be written to the current directory.
Input:
self, [port=8200], [address=localhost], [open_viewer=True], [options=]) |
Start a web server for this repository.
This server is very nice - you can browse all files in the repository, see their changelogs, see who wrote any given line, etc. Very nice.
Input:
self, [name=None]) |
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.
self, bundle, [update=True], [options=]) |
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:
self, [options=]) |
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:
self, [options=]) |
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:
self, [files=], [rev=None]) |
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 commited changes.
Input:
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.
Special Functions: __call__,
__init__,
__repr__,
_changed_files,
_ensure_safe,
_warning
self, [cmd=None], [interactive=True]) |
Run 'hg cmd' where cmd is an arbitrary string in the hg repository.
Input:
self) |
Ensure that the repository is in a safe state to have changes applied to it, i.e., that all changes to controlled files in the working directory are recorded.
See About this document... for information on suggesting changes.